Skip to content

Commit a9bb7d3

Browse files
authored
Merge pull request #24839 from JuliaLang/ajf/permutedims
RFC: Make matrix transpose default for `permutedims`
2 parents 95b6488 + 2ba2556 commit a9bb7d3

File tree

5 files changed

+43
-8
lines changed

5 files changed

+43
-8
lines changed

NEWS.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -430,6 +430,12 @@ Library improvements
430430
definition relies on `ncodeunits` however, so for optimal performance you may need to
431431
define a custom method for that function.
432432

433+
* `permutedims(m::AbstractMatrix)` is now short for `permutedims(m, (2,1))`, and is now a
434+
more convenient way of making a "shallow transpose" of a 2D array. This is the
435+
recommended approach for manipulating arrays of data, rather than the recursively
436+
defined, linear-algebra function `transpose`. Similarly,
437+
`permutedims(v::AbstractVector)` will create a row matrix ([#24839]).
438+
433439
Compiler/Runtime improvements
434440
-----------------------------
435441

base/linalg/transpose.jl

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -147,7 +147,11 @@ end
147147
"""
148148
transpose(A::AbstractMatrix)
149149
150-
The transposition operator (`.'`).
150+
The transposition operator (`.'`). Note that the transposition is applied recursively to
151+
elements.
152+
153+
This operation is intended for linear algebra usage - for general data manipulation see
154+
[`permutedims`](@ref), which is non-recursive.
151155
152156
# Examples
153157
```jldoctest

base/operators.jl

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -744,7 +744,11 @@ fldmod1(x::T, y::T) where {T<:Integer} = (fld1(x,y), mod1(x,y))
744744
"""
745745
adjoint(A)
746746
747-
The conjugate transposition operator (`'`).
747+
The conjugate transposition operator (`'`). Note that `adjoint` is applied recursively to
748+
elements.
749+
750+
This operation is intended for linear algebra usage - for general data manipulation see
751+
[`permutedims`](@ref).
748752
749753
# Examples
750754
```jldoctest

base/permuteddimsarray.jl

Lines changed: 21 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,8 @@
22

33
module PermutedDimsArrays
44

5-
export permutedims, PermutedDimsArray
5+
import Base: permutedims, permutedims!
6+
export PermutedDimsArray
67

78
# Some day we will want storage-order-aware iteration, so put perm in the parameters
89
struct PermutedDimsArray{T,N,perm,iperm,AA<:AbstractArray} <: AbstractArray{T,N}
@@ -77,11 +78,10 @@ end
7778
@inline genperm(I, perm::AbstractVector{Int}) = genperm(I, (perm...,))
7879

7980
"""
80-
permutedims(A, perm)
81+
permutedims(A::AbstractArray, perm)
8182
8283
Permute the dimensions of array `A`. `perm` is a vector specifying a permutation of length
83-
`ndims(A)`. This is a generalization of transpose for multi-dimensional arrays. Transpose is
84-
equivalent to `permutedims(A, [2,1])`.
84+
`ndims(A)`.
8585
8686
See also: [`PermutedDimsArray`](@ref).
8787
@@ -108,11 +108,26 @@ julia> permutedims(A, [3, 2, 1])
108108
6 8
109109
```
110110
"""
111-
function Base.permutedims(A::AbstractArray, perm)
111+
function permutedims(A::AbstractArray, perm)
112112
dest = similar(A, genperm(indices(A), perm))
113113
permutedims!(dest, A, perm)
114114
end
115115

116+
"""
117+
permutedims(m::AbstractMatrix)
118+
119+
Permute the dimensions of the matrix `m`, by flipping the elements across the diagonal of
120+
the matrix. Differs from [`transpose`](@ref) in that the operation is not recursive.
121+
"""
122+
permutedims(A::AbstractMatrix) = permutedims(A, (2,1))
123+
124+
"""
125+
permutedims(v::AbstractVector)
126+
127+
Reshape vector `v` into a `1 × length(v)` row matrix.
128+
"""
129+
permutedims(v::AbstractVector) = reshape(v, (1, length(v)))
130+
116131
"""
117132
permutedims!(dest, src, perm)
118133
@@ -124,7 +139,7 @@ regions.
124139
125140
See also [`permutedims`](@ref).
126141
"""
127-
function Base.permutedims!(dest, src::AbstractArray, perm)
142+
function permutedims!(dest, src::AbstractArray, perm)
128143
Base.checkdims_perm(dest, src, perm)
129144
P = PermutedDimsArray(dest, invperm(perm))
130145
_copy!(P, src)

test/arrayops.jl

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -577,6 +577,12 @@ end
577577
@test isequal(A,permutedims(permutedims(A,perm),invperm(perm)))
578578
@test isequal(A,permutedims(permutedims(A,invperm(perm)),perm))
579579
end
580+
581+
m = [1 2; 3 4]
582+
@test permutedims(m) == [1 3; 2 4]
583+
584+
v = [1,2,3]
585+
@test permutedims(v) == [1 2 3]
580586
end
581587

582588
@testset "circshift" begin

0 commit comments

Comments
 (0)