# permutedims!

permutedims!(dest, src, perm)

Permute the dimensions of array `src` and store the result in the array `dest`. `perm` is a vector specifying a permutation of length `ndims(src)`. The preallocated array `dest` should have `size(dest) == size(src)[perm]` and is completely overwritten. No in-place permutation is supported and unexpected results will happen if `src` and `dest` have overlapping memory regions.

## Examples

1. Permute dimensions of a matrix:

``````julia> A = [1 2 3; 4 5 6; 7 8 9];
julia> B = similar(A, (3, 3));
julia> permutedims!(B, A, (2, 1))
3×3 Array{Int64,2}:
1  4  7
2  5  8
3  6  9``````

This example permutes the dimensions of matrix `A` using the permutation `(2, 1)` and stores the result in matrix `B`.

2. Permute dimensions of a 3D array:

``````julia> C = rand(1:9, (2, 3, 4));
julia> D = similar(C, (3, 2, 4));
julia> permutedims!(D, C, (3, 2, 1))
3×2×4 Array{Int64,3}:
[:, :, 1] =
2  5
9  3
6  7

[:, :, 2] =
4  6
8  9
1  2

[:, :, 3] =
3  1
2  4
5  8

[:, :, 4] =
7  3
5  6
9  1``````

This example permutes the dimensions of a 3D array `C` using the permutation `(3, 2, 1)` and stores the result in array `D`.

Common mistake example:

``````julia> X = [1 2 3];
julia> Y = [1 2 3];
julia> permutedims!(X, Y, (1, 2))
ERROR: MethodError: no method matching permutedims!(::Array{Int64,2}, ::Array{Int64,2}, ::Tuple{Int64,Int64})``````

In this example, the function is called with `X` and `Y` as arguments, but `X` is not a preallocated array. It's important to ensure that the destination array (`dest`) is preallocated and has the correct size before using `permutedims!`.