From 7e77145d15074a34bb712b64fa882a6fd8b647f5 Mon Sep 17 00:00:00 2001
From: Ed Schmerling <ednerd@gmail.com>
Date: Thu, 7 Apr 2016 16:01:37 -0700
Subject: [PATCH] Document recursive (c)transpose and fix #15512

---
 base/arraymath.jl        |  7 ++++---
 base/docs/helpdb/Base.jl |  7 +++++--
 doc/stdlib/linalg.rst    |  4 ++--
 test/arrayops.jl         | 14 ++++++++++++++
 4 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/base/arraymath.jl b/base/arraymath.jl
index 7427b73c186364..b407c77c1453fb 100644
--- a/base/arraymath.jl
+++ b/base/arraymath.jl
@@ -367,18 +367,19 @@ function ccopy!(B, A)
     end
 end
 
+transpose{T<:AbstractVector}(::Type{T}) = Matrix{eltype(T)}
 function transpose(A::AbstractMatrix)
-    B = similar(A, size(A, 2), size(A, 1))
+    B = Array(transpose(eltype(A)), size(A, 2), size(A, 1))
     transpose!(B, A)
 end
 function ctranspose(A::AbstractMatrix)
-    B = similar(A, size(A, 2), size(A, 1))
+    B = Array(transpose(eltype(A)), size(A, 2), size(A, 1))
     ctranspose!(B, A)
 end
 ctranspose{T<:Real}(A::AbstractVecOrMat{T}) = transpose(A)
 
 transpose(x::AbstractVector) = [ transpose(v) for i=1, v in x ]
-ctranspose{T}(x::AbstractVector{T}) = T[ ctranspose(v) for i=1, v in x ] #Fixme comprehension
+ctranspose{T}(x::AbstractVector{T}) = transpose(T)[ ctranspose(v) for i=1, v in x ] #Fixme comprehension
 
 _cumsum_type{T<:Number}(v::AbstractArray{T}) = typeof(+zero(T))
 _cumsum_type(v) = typeof(v[1]+v[1])
diff --git a/base/docs/helpdb/Base.jl b/base/docs/helpdb/Base.jl
index e11f30621b7318..45195630bb11b1 100644
--- a/base/docs/helpdb/Base.jl
+++ b/base/docs/helpdb/Base.jl
@@ -2818,7 +2818,8 @@ find(f, A)
 """
     ctranspose(A)
 
-The conjugate transposition operator (`'`).
+The conjugate transposition operator (`'`). Operates recursively on arrays with vector or
+matrix element type (e.g., block matrices).
 """
 ctranspose
 
@@ -5115,7 +5116,9 @@ lock
 """
     transpose(A)
 
-The transposition operator (`.'`).
+The transposition operator (`.'`). Operates recursively on arrays with vector or matrix
+element type (e.g., block matrices). Non-recursive behavior may be obtained in such cases
+by calling `permutedims(A, [2,1])`.
 """
 transpose
 
diff --git a/doc/stdlib/linalg.rst b/doc/stdlib/linalg.rst
index a528f3a441770c..6f5e4afc29c9f1 100644
--- a/doc/stdlib/linalg.rst
+++ b/doc/stdlib/linalg.rst
@@ -1128,7 +1128,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    .. Docstring generated from Julia source
 
-   The transposition operator (``.'``\ ).
+   The transposition operator (``.'``\ ). Operates recursively on arrays with vector or matrix element type (e.g., block matrices). Non-recursive behavior may be obtained in such cases by calling ``permutedims(A, [2,1])``\ .
 
 .. function:: transpose!(dest,src)
 
@@ -1140,7 +1140,7 @@ Linear algebra functions in Julia are largely implemented by calling functions f
 
    .. Docstring generated from Julia source
 
-   The conjugate transposition operator (``'``\ ).
+   The conjugate transposition operator (``'``\ ). Operates recursively on arrays with vector or matrix element type (e.g., block matrices).
 
 .. function:: ctranspose!(dest,src)
 
diff --git a/test/arrayops.jl b/test/arrayops.jl
index 802ed181bcc0f3..2fd6e3b6786d7c 100644
--- a/test/arrayops.jl
+++ b/test/arrayops.jl
@@ -1256,6 +1256,20 @@ a = zeros(Complex,1,5)
 ctranspose!(a,b)
 @test a == ones(Complex,1,5)
 
+# block matrix/vector transposes
+unblock(x::AbstractMatrix) = hvcat(size(x,2), permutedims(x, [2,1])...)
+unblock(x::AbstractVector) = vcat(x...)
+a = [rand(3,3) for i=1:3, j=1:3]
+b = [rand(3) for i=1:3]
+ua = unblock(a)
+ub = unblock(b)
+@test (b'*a*b)[1][1] ≈ (ub'*ua*ub)[1] ≈ (b'*a'*b)[1][1] ≈ (ub'*ua'*ub)[1]
+a = [rand(3,3) + rand(3,3)*im for i=1:3, j=1:3]
+b = [rand(3) + rand(3)*im for i=1:3]
+ua = unblock(a)
+ub = unblock(b)
+@test (b'*a*b)[1][1] ≈ (ub'*ua*ub)[1] ≈ conj((b'*a'*b)[1][1]) ≈ conj((ub'*ua'*ub)[1])
+
 # flipdim
 a = rand(5,3)
 @test flipdim(flipdim(a,2),2) == a