diff --git a/base/abstractarray.jl b/base/abstractarray.jl index 82e679aec21a9..31e84ab985995 100644 --- a/base/abstractarray.jl +++ b/base/abstractarray.jl @@ -1365,6 +1365,49 @@ foreach(f, itrs...) = (for z in zip(itrs...); f(z...); end; nothing) ## transform any set of dimensions ## dims specifies which dimensions will be transformed. for example ## dims==1:2 will call f on all slices A[:,:,...] +""" + mapslices(f, A, dims) + +Transform the given dimensions of array `A` using function `f`. `f` is called on each slice +of `A` of the form `A[...,:,...,:,...]`. `dims` is an integer vector specifying where the +colons go in this expression. The results are concatenated along the remaining dimensions. +For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]` +for all `i` and `j`. + +```jldoctest +julia> a = reshape(collect(1:16),(2,2,2,2)) +2×2×2×2 Array{Int64,4}: +[:, :, 1, 1] = + 1 3 + 2 4 + +[:, :, 2, 1] = + 5 7 + 6 8 + +[:, :, 1, 2] = + 9 11 + 10 12 + +[:, :, 2, 2] = + 13 15 + 14 16 + +julia> mapslices(sum, a, [1,2]) +1×1×2×2 Array{Int64,4}: +[:, :, 1, 1] = + 10 + +[:, :, 2, 1] = + 26 + +[:, :, 1, 2] = + 42 + +[:, :, 2, 2] = + 58 +``` +""" mapslices(f, A::AbstractArray, dims) = mapslices(f, A, [dims...]) function mapslices(f, A::AbstractArray, dims::AbstractVector) if isempty(dims) diff --git a/base/arraymath.jl b/base/arraymath.jl index 1f4e636228512..0de1bd39486f5 100644 --- a/base/arraymath.jl +++ b/base/arraymath.jl @@ -159,6 +159,23 @@ function flipdim{T}(A::Array{T}, d::Integer) return B end +""" + rotl90(A) + +Rotate matrix `A` left 90 degrees. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rotl90(a) +2×2 Array{Int64,2}: + 2 4 + 1 3 +``` +""" function rotl90(A::AbstractMatrix) ind1, ind2 = indices(A) B = similar(A, (ind2,ind1)) @@ -168,6 +185,24 @@ function rotl90(A::AbstractMatrix) end return B end + +""" + rotr90(A) + +Rotate matrix `A` right 90 degrees. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rotr90(a) +2×2 Array{Int64,2}: + 3 1 + 4 2 +``` +""" function rotr90(A::AbstractMatrix) ind1, ind2 = indices(A) B = similar(A, (ind2,ind1)) @@ -177,6 +212,23 @@ function rotr90(A::AbstractMatrix) end return B end +""" + rot180(A) + +Rotate matrix `A` 180 degrees. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rot180(a) +2×2 Array{Int64,2}: + 4 3 + 2 1 +``` +""" function rot180(A::AbstractMatrix) B = similar(A) ind1, ind2 = indices(A,1), indices(A,2) @@ -186,13 +238,102 @@ function rot180(A::AbstractMatrix) end return B end +""" + rotl90(A, k) + +Rotate matrix `A` left 90 degrees an integer `k` number of times. +If `k` is zero or a multiple of four, this is equivalent to a `copy`. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rotl90(a,1) +2×2 Array{Int64,2}: + 2 4 + 1 3 + +julia> rotl90(a,2) +2×2 Array{Int64,2}: + 4 3 + 2 1 + +julia> rotl90(a,3) +2×2 Array{Int64,2}: + 3 1 + 4 2 + +julia> rotl90(a,4) +2×2 Array{Int64,2}: + 1 2 + 3 4 +``` +""" function rotl90(A::AbstractMatrix, k::Integer) k = mod(k, 4) k == 1 ? rotl90(A) : k == 2 ? rot180(A) : k == 3 ? rotr90(A) : copy(A) end +""" + rotr90(A, k) + +Rotate matrix `A` right 90 degrees an integer `k` number of times. If `k` is zero or a +multiple of four, this is equivalent to a `copy`. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rotr90(a,1) +2×2 Array{Int64,2}: + 3 1 + 4 2 + +julia> rotr90(a,2) +2×2 Array{Int64,2}: + 4 3 + 2 1 + +julia> rotr90(a,3) +2×2 Array{Int64,2}: + 2 4 + 1 3 + +julia> rotr90(a,4) +2×2 Array{Int64,2}: + 1 2 + 3 4 +``` +""" rotr90(A::AbstractMatrix, k::Integer) = rotl90(A,-k) +""" + rot180(A, k) + +Rotate matrix `A` 180 degrees an integer `k` number of times. +If `k` is even, this is equivalent to a `copy`. + +```jldoctest +julia> a = [1 2; 3 4] +2×2 Array{Int64,2}: + 1 2 + 3 4 + +julia> rot180(a,1) +2×2 Array{Int64,2}: + 4 3 + 2 1 + +julia> rot180(a,2) +2×2 Array{Int64,2}: + 1 2 + 3 4 +``` +""" rot180(A::AbstractMatrix, k::Integer) = mod(k, 2) == 1 ? rot180(A) : copy(A) ## Transpose ## diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl index 9599c3a57dbe6..b8ab785fd9778 100644 --- a/base/docs/helpdb/Base.jl +++ b/base/docs/helpdb/Base.jl @@ -490,19 +490,6 @@ Get a backtrace object for the current program point. """ backtrace -""" - reducedim(f, A, dims[, initial]) - -Reduce 2-argument function `f` along dimensions of `A`. `dims` is a vector specifying the -dimensions to reduce, and `initial` is the initial value to use in the reductions. For `+`, `*`, -`max` and `min` the `initial` argument is optional. - -The associativity of the reduction is implementation-dependent; if you need a particular -associativity, e.g. left-to-right, you should write your own loop. See documentation for -`reduce`. -""" -reducedim - """ -(x) @@ -1105,17 +1092,6 @@ representable. """ ceil -""" - mapslices(f, A, dims) - -Transform the given dimensions of array `A` using function `f`. `f` is called on each slice -of `A` of the form `A[...,:,...,:,...]`. `dims` is an integer vector specifying where the -colons go in this expression. The results are concatenated along the remaining dimensions. -For example, if `dims` is `[1,2]` and `A` is 4-dimensional, `f` is called on `A[:,:,i,j]` -for all `i` and `j`. -""" -mapslices - """ issocket(path) -> Bool @@ -2321,15 +2297,6 @@ Bessel function of the second kind of order 1, ``Y_1(x)``. """ bessely1 -""" - cumprod(A, [dim]) - -Cumulative product along a dimension `dim` (defaults to 1). See also -[`cumprod!`](:func:`cumprod!`) to use a preallocated output array, both for performance and -to control the precision of the output (e.g. to avoid overflow). -""" -cumprod - """ besseljx(nu, x) @@ -3054,21 +3021,6 @@ block to create a new scope with copies of all variables referenced in the expre """ :@async -""" - rotr90(A) - -Rotate matrix `A` right 90 degrees. -""" -rotr90(A) - -""" - rotr90(A, k) - -Rotate matrix `A` right 90 degrees an integer `k` number of times. If `k` is zero or a -multiple of four, this is equivalent to a `copy`. -""" -rotr90(A, k) - """ readdir([dir]) -> Vector{String} @@ -3523,21 +3475,6 @@ Number of ways to choose `k` out of `n` items. """ binomial -""" - rot180(A) - -Rotate matrix `A` 180 degrees. -""" -rot180(A) - -""" - rot180(A, k) - -Rotate matrix `A` 180 degrees an integer `k` number of times. If `k` is even, this is -equivalent to a `copy`. -""" -rot180(A, k) - """ .<=(x, y) .≤(x,y) @@ -3903,21 +3840,6 @@ x == div(x,y)*y + rem(x,y) """ rem -""" - rotl90(A) - -Rotate matrix `A` left 90 degrees. -""" -rotl90(A) - -""" - rotl90(A, k) - -Rotate matrix `A` left 90 degrees an integer `k` number of times. If `k` is zero or a -multiple of four, this is equivalent to a `copy`. -""" -rotl90(A, k) - """ info(msg) @@ -5623,14 +5545,6 @@ handle comparison to other types via promotion rules where possible. """ Base.:(==) -""" - mapreducedim(f, op, A, dims[, initial]) - -Evaluates to the same as `reducedim(op, map(f, A), dims, f(initial))`, but is generally -faster because the intermediate array is avoided. -""" -mapreducedim - """ seekstart(s) @@ -6415,15 +6329,6 @@ the group owning the file """ operm -""" - cumsum(A, [dim]) - -Cumulative sum along a dimension `dim` (defaults to 1). See also [`cumsum!`](:func:`cumsum!`) -to use a preallocated output array, both for performance and to control the precision of the -output (e.g. to avoid overflow). -""" -cumsum - """ rpad(string, n, p) diff --git a/base/multidimensional.jl b/base/multidimensional.jl index f4f4a676d2112..385e9e218f891 100644 --- a/base/multidimensional.jl +++ b/base/multidimensional.jl @@ -496,8 +496,56 @@ for (f, fmod, op) = ((:cummin, :_cummin!, :min), (:cummax, :_cummax!, :max)) @eval ($f)(A::AbstractArray) = ($f)(A, 1) end - cumsum(A::AbstractArray, axis::Integer=1) = cumsum!(similar(A, Base._cumsum_type(A)), A, axis) +""" + cumsum(A, dim=1) + +Cumulative sum along a dimension `dim` (defaults to 1). See also [`cumsum!`](:func:`cumsum!`) +to use a preallocated output array, both for performance and to control the precision of the +output (e.g. to avoid overflow). + +```jldoctest +julia> a = [1 2 3; 4 5 6] +2×3 Array{Int64,2}: + 1 2 3 + 4 5 6 + +julia> cumsum(a,1) +2×3 Array{Int64,2}: + 1 2 3 + 5 7 9 + +julia> cumsum(a,2) +2×3 Array{Int64,2}: + 1 3 6 + 4 9 15 +``` +""" +cumsum(A::AbstractArray, axis::Integer=1) = cumsum!(similar(A, Base._cumsum_type(A)), A, axis) cumsum!(B, A::AbstractArray) = cumsum!(B, A, 1) +""" + cumprod(A, dim=1) + +Cumulative product along a dimension `dim` (defaults to 1). See also +[`cumprod!`](:func:`cumprod!`) to use a preallocated output array, both for performance and +to control the precision of the output (e.g. to avoid overflow). + +```jldoctest +julia> a = [1 2 3; 4 5 6] +2×3 Array{Int64,2}: + 1 2 3 + 4 5 6 + +julia> cumprod(a,1) +2×3 Array{Int64,2}: + 1 2 3 + 4 10 18 + +julia> cumprod(a,2) +2×3 Array{Int64,2}: + 1 2 6 + 4 20 120 +``` +""" cumprod(A::AbstractArray, axis::Integer=1) = cumprod!(similar(A), A, axis) cumprod!(B, A) = cumprod!(B, A, 1) diff --git a/base/reducedim.jl b/base/reducedim.jl index f6fa07169a511..047cc9af80e92 100644 --- a/base/reducedim.jl +++ b/base/reducedim.jl @@ -225,11 +225,65 @@ mapreducedim!(f, op, R::AbstractArray, A::AbstractArray) = reducedim!{RT}(op, R::AbstractArray{RT}, A::AbstractArray) = mapreducedim!(identity, op, R, A, zero(RT)) +""" + mapreducedim(f, op, A, region[, v0]) + +Evaluates to the same as `reducedim(op, map(f, A), region, f(v0))`, but is generally +faster because the intermediate array is avoided. + +```jldoctest +julia> a = reshape(collect(1:16), (4,4)) +4×4 Array{Int64,2}: + 1 5 9 13 + 2 6 10 14 + 3 7 11 15 + 4 8 12 16 + +julia> mapreducedim(isodd, *, a, 1) +1×4 Array{Bool,2}: + false false false false + +julia> mapreducedim(isodd, |, a, 1, true) +1×4 Array{Bool,2}: + true true true true +``` +""" mapreducedim(f, op, A::AbstractArray, region, v0) = mapreducedim!(f, op, reducedim_initarray(A, region, v0), A) mapreducedim{T}(f, op, A::AbstractArray{T}, region) = mapreducedim!(f, op, reducedim_init(f, op, A, region), A) +""" + reducedim(f, A, region[, v0]) + +Reduce 2-argument function `f` along dimensions of `A`. `region` is a vector specifying the +dimensions to reduce, and `v0` is the initial value to use in the reductions. For `+`, `*`, +`max` and `min` the `v0` argument is optional. + +The associativity of the reduction is implementation-dependent; if you need a particular +associativity, e.g. left-to-right, you should write your own loop. See documentation for +[`reduce`](:func:`reduce`). + +```jldoctest +julia> a = reshape(collect(1:16), (4,4)) +4×4 Array{Int64,2}: + 1 5 9 13 + 2 6 10 14 + 3 7 11 15 + 4 8 12 16 + +julia> reducedim(max, a, 2) +4×1 Array{Int64,2}: + 13 + 14 + 15 + 16 + +julia> reducedim(max, a, 1) +1×4 Array{Int64,2}: + 4 8 12 16 +``` +""" reducedim(op, A::AbstractArray, region, v0) = mapreducedim(identity, op, A, region, v0) reducedim(op, A::AbstractArray, region) = mapreducedim(identity, op, A, region) diff --git a/doc/stdlib/arrays.rst b/doc/stdlib/arrays.rst index 448dd55c0caa9..f72f67f72b10a 100644 --- a/doc/stdlib/arrays.rst +++ b/doc/stdlib/arrays.rst @@ -657,24 +657,58 @@ Indexing, Assignment, and Concatenation Array functions --------------- -.. function:: cumprod(A, [dim]) +.. function:: cumprod(A, dim=1) .. Docstring generated from Julia source Cumulative product along a dimension ``dim`` (defaults to 1). See also :func:`cumprod!` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). + .. doctest:: + + julia> a = [1 2 3; 4 5 6] + 2×3 Array{Int64,2}: + 1 2 3 + 4 5 6 + + julia> cumprod(a,1) + 2×3 Array{Int64,2}: + 1 2 3 + 4 10 18 + + julia> cumprod(a,2) + 2×3 Array{Int64,2}: + 1 2 6 + 4 20 120 + .. function:: cumprod!(B, A, [dim]) .. Docstring generated from Julia source Cumulative product of ``A`` along a dimension, storing the result in ``B``\ . The dimension defaults to 1. -.. function:: cumsum(A, [dim]) +.. function:: cumsum(A, dim=1) .. Docstring generated from Julia source Cumulative sum along a dimension ``dim`` (defaults to 1). See also :func:`cumsum!` to use a preallocated output array, both for performance and to control the precision of the output (e.g. to avoid overflow). + .. doctest:: + + julia> a = [1 2 3; 4 5 6] + 2×3 Array{Int64,2}: + 1 2 3 + 4 5 6 + + julia> cumsum(a,1) + 2×3 Array{Int64,2}: + 1 2 3 + 5 7 9 + + julia> cumsum(a,2) + 2×3 Array{Int64,2}: + 1 3 6 + 4 9 15 + .. function:: cumsum!(B, A, [dim]) .. Docstring generated from Julia source @@ -717,49 +751,193 @@ Array functions Rotate matrix ``A`` 180 degrees. + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rot180(a) + 2×2 Array{Int64,2}: + 4 3 + 2 1 + .. function:: rot180(A, k) .. Docstring generated from Julia source Rotate matrix ``A`` 180 degrees an integer ``k`` number of times. If ``k`` is even, this is equivalent to a ``copy``\ . + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rot180(a,1) + 2×2 Array{Int64,2}: + 4 3 + 2 1 + + julia> rot180(a,2) + 2×2 Array{Int64,2}: + 1 2 + 3 4 + .. function:: rotl90(A) .. Docstring generated from Julia source Rotate matrix ``A`` left 90 degrees. + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rotl90(a) + 2×2 Array{Int64,2}: + 2 4 + 1 3 + .. function:: rotl90(A, k) .. Docstring generated from Julia source Rotate matrix ``A`` left 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rotl90(a,1) + 2×2 Array{Int64,2}: + 2 4 + 1 3 + + julia> rotl90(a,2) + 2×2 Array{Int64,2}: + 4 3 + 2 1 + + julia> rotl90(a,3) + 2×2 Array{Int64,2}: + 3 1 + 4 2 + + julia> rotl90(a,4) + 2×2 Array{Int64,2}: + 1 2 + 3 4 + .. function:: rotr90(A) .. Docstring generated from Julia source Rotate matrix ``A`` right 90 degrees. + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rotr90(a) + 2×2 Array{Int64,2}: + 3 1 + 4 2 + .. function:: rotr90(A, k) .. Docstring generated from Julia source Rotate matrix ``A`` right 90 degrees an integer ``k`` number of times. If ``k`` is zero or a multiple of four, this is equivalent to a ``copy``\ . -.. function:: reducedim(f, A, dims[, initial]) + .. doctest:: + + julia> a = [1 2; 3 4] + 2×2 Array{Int64,2}: + 1 2 + 3 4 + + julia> rotr90(a,1) + 2×2 Array{Int64,2}: + 3 1 + 4 2 + + julia> rotr90(a,2) + 2×2 Array{Int64,2}: + 4 3 + 2 1 + + julia> rotr90(a,3) + 2×2 Array{Int64,2}: + 2 4 + 1 3 + + julia> rotr90(a,4) + 2×2 Array{Int64,2}: + 1 2 + 3 4 + +.. function:: reducedim(f, A, region[, v0]) .. Docstring generated from Julia source - Reduce 2-argument function ``f`` along dimensions of ``A``\ . ``dims`` is a vector specifying the dimensions to reduce, and ``initial`` is the initial value to use in the reductions. For ``+``\ , ``*``\ , ``max`` and ``min`` the ``initial`` argument is optional. + Reduce 2-argument function ``f`` along dimensions of ``A``\ . ``region`` is a vector specifying the dimensions to reduce, and ``v0`` is the initial value to use in the reductions. For ``+``\ , ``*``\ , ``max`` and ``min`` the ``v0`` argument is optional. + + The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for :func:`reduce`\ . + + .. doctest:: - The associativity of the reduction is implementation-dependent; if you need a particular associativity, e.g. left-to-right, you should write your own loop. See documentation for ``reduce``\ . + julia> a = reshape(collect(1:16), (4,4)) + 4×4 Array{Int64,2}: + 1 5 9 13 + 2 6 10 14 + 3 7 11 15 + 4 8 12 16 + + julia> reducedim(max, a, 2) + 4×1 Array{Int64,2}: + 13 + 14 + 15 + 16 + + julia> reducedim(max, a, 1) + 1×4 Array{Int64,2}: + 4 8 12 16 -.. function:: mapreducedim(f, op, A, dims[, initial]) +.. function:: mapreducedim(f, op, A, region[, v0]) .. Docstring generated from Julia source - Evaluates to the same as ``reducedim(op, map(f, A), dims, f(initial))``\ , but is generally faster because the intermediate array is avoided. + Evaluates to the same as ``reducedim(op, map(f, A), region, f(v0))``\ , but is generally faster because the intermediate array is avoided. + + .. doctest:: + + julia> a = reshape(collect(1:16), (4,4)) + 4×4 Array{Int64,2}: + 1 5 9 13 + 2 6 10 14 + 3 7 11 15 + 4 8 12 16 + + julia> mapreducedim(isodd, *, a, 1) + 1×4 Array{Bool,2}: + false false false false + + julia> mapreducedim(isodd, |, a, 1, true) + 1×4 Array{Bool,2}: + true true true true .. function:: mapslices(f, A, dims) @@ -767,6 +945,40 @@ Array functions Transform the given dimensions of array ``A`` using function ``f``\ . ``f`` is called on each slice of ``A`` of the form ``A[...,:,...,:,...]``\ . ``dims`` is an integer vector specifying where the colons go in this expression. The results are concatenated along the remaining dimensions. For example, if ``dims`` is ``[1,2]`` and ``A`` is 4-dimensional, ``f`` is called on ``A[:,:,i,j]`` for all ``i`` and ``j``\ . + .. doctest:: + + julia> a = reshape(collect(1:16),(2,2,2,2)) + 2×2×2×2 Array{Int64,4}: + [:, :, 1, 1] = + 1 3 + 2 4 + + [:, :, 2, 1] = + 5 7 + 6 8 + + [:, :, 1, 2] = + 9 11 + 10 12 + + [:, :, 2, 2] = + 13 15 + 14 16 + + julia> mapslices(sum, a, [1,2]) + 1×1×2×2 Array{Int64,4}: + [:, :, 1, 1] = + 10 + + [:, :, 2, 1] = + 26 + + [:, :, 1, 2] = + 42 + + [:, :, 2, 2] = + 58 + .. function:: sum_kbn(A) .. Docstring generated from Julia source