Merge pull request #20384 from JuliaLang/teh/pd_export

Export PermutedDimsArray
JuliaLang · Feb 3, 2017 · f66c866 · f66c866
2 parents d7cff44 + 591d6b9
commit f66c866
Show file tree

Hide file tree

Showing 4 changed files with 31 additions and 4 deletions.
diff --git a/base/exports.jl b/base/exports.jl
@@ -81,6 +81,7 @@ export
     OrdinalRange,
     Pair,
     PartialQuickSort,
+    PermutedDimsArray,
     PollingFileWatcher,
     QuickSort,
     Range,

diff --git a/base/permuteddimsarray.jl b/base/permuteddimsarray.jl
@@ -2,7 +2,7 @@
 
 module PermutedDimsArrays
 
-export permutedims
+export permutedims, PermutedDimsArray
 
 # Some day we will want storage-order-aware iteration, so put perm in the parameters
 immutable PermutedDimsArray{T,N,perm,iperm,AA<:AbstractArray} <: AbstractArray{T,N}
@@ -16,6 +16,29 @@ immutable PermutedDimsArray{T,N,perm,iperm,AA<:AbstractArray} <: AbstractArray{T
     end
 end
 
+"""
+    PermutedDimsArray(A, perm) -> B
+
+Given an AbstractArray `A`, create a view `B` such that the
+dimensions appear to be permuted. Similar to `permutedims`, except
+that no copying occurs (`B` shares storage with `A`).
+
+See also: [`permutedims`](@ref).
+
+# Example
+
+```jldoctest
+julia> A = rand(3,5,4);
+
+julia> B = PermutedDimsArray(A, (3,1,2));
+
+julia> size(B)
+(4, 3, 5)
+
+julia> B[3,1,2] == A[1,2,3]
+true
+```
+"""
 function PermutedDimsArray{T,N}(data::AbstractArray{T,N}, perm)
     length(perm) == N || throw(ArgumentError(string(perm, " is not a valid permutation of dimensions 1:", N)))
     iperm = invperm(perm)
@@ -50,6 +73,8 @@ Permute the dimensions of array `A`. `perm` is a vector specifying a permutation
 `ndims(A)`. This is a generalization of transpose for multi-dimensional arrays. Transpose is
 equivalent to `permutedims(A, [2,1])`.
 
+See also: [`PermutedDimsArray`](@ref).
+
 ```jldoctest
 julia> A = reshape(collect(1:8), (2,2,2))
 2×2×2 Array{Int64,3}:

diff --git a/doc/src/stdlib/arrays.md b/doc/src/stdlib/arrays.md
@@ -96,6 +96,7 @@ Base.findprev(::Function, ::Any, ::Integer)
 Base.findprev(::Any, ::Any, ::Integer)
 Base.permutedims
 Base.permutedims!
+Base.PermutedDimsArray
 Base.squeeze
 Base.vec
 Base.promote_shape

diff --git a/test/arrayops.jl b/test/arrayops.jl
@@ -508,12 +508,12 @@ end
     c = convert(Array, s)
     for p in ([1,2,3], [1,3,2], [2,1,3], [2,3,1], [3,1,2], [3,2,1])
         @test permutedims(s, p) == permutedims(c, p)
-        @test Base.PermutedDimsArrays.PermutedDimsArray(s, p) == permutedims(c, p)
+        @test PermutedDimsArray(s, p) == permutedims(c, p)
     end
     @test_throws ArgumentError permutedims(a, (1,1,1))
     @test_throws ArgumentError permutedims(s, (1,1,1))
-    @test_throws ArgumentError Base.PermutedDimsArrays.PermutedDimsArray(a, (1,1,1))
-    @test_throws ArgumentError Base.PermutedDimsArrays.PermutedDimsArray(s, (1,1,1))
+    @test_throws ArgumentError PermutedDimsArray(a, (1,1,1))
+    @test_throws ArgumentError PermutedDimsArray(s, (1,1,1))
 
     for A in [rand(1,2,3,4),rand(2,2,2,2),rand(5,6,5,6),rand(1,1,1,1)]
         perm = randperm(4)