Scilab-Branch-6.1-GIT
Change language to:
Français - 日本語 - Português - Русский
Scilab Help >> Elementary Functions > Matrix - shaping > permute

# permute

permutes the dimensions of an array

### Syntax

`y = permute(x, dims)`

### Arguments

x

an array with any number of dimensions (0, 1, 2, or any number n>2), of any data type: booleans, integers, decimal real or complex numbers, polynomials, rationals, array of structures, array of cells.

dims

a valid permutation of 1:n>=nmin where n is the number of dimensions of the desired array, at least as many as `nmin = ndims(x)`.

The dimension `#i` in `y` was the dimension `#dims(i)` in `x`.

y

an array with the contents of `x`, with identical but permuted sizes.

### Description

Permutes the dimensions of the array according to `dims`.

 Any trailing dimension of the result `y` that becomes a singleton (has a new size equal to 1, coming from a formerly non trailing singleton dimension) is automatically ignored (squeezed).
 `permute()` is mainly interesting when dealing with hypermatrices. To only transpose a matrix (permute its rows into columns and vice-versa), the `.'` or `'` operators should be prefered.

### Examples

```// Example 1: A matrix becomes an hypermatrix with one side of size==1
//            (here the number of rows)
x = [1 2 3; 4 5 6]
y = permute(x,[3 1 2])```
```--> x = [1 2 3; 4 5 6]
x  =
1.   2.   3.
4.   5.   6.

--> y = permute(x,[3 1 2])
y  =
(:,:,1)
1.   4.
(:,:,2)
2.   5.
(:,:,3)
3.   6.
```
```// Example 2: With encoded integers
x = int8(matrix(1:24, [3 4 2]))
y = permute(x, [2 3 1])```
```--> x = int8(matrix(1:24, [3 4 2]))
x  =
(:,:,1)
1  4  7  10
2  5  8  11
3  6  9  12
(:,:,2)
13  16  19  22
14  17  20  23
15  18  21  24

--> y = permute(x, [2 3 1])
y  =
(:,:,1)
1  13
4  16
7  19
10  22
(:,:,2)
2  14
5  17
8  20
11  23
(:,:,3)
3  15
6  18
9  21
12  24
```
```// Example 3:
x = matrix(1:8, [2 1 4])
y = permute(x, [3 1 2]);
// The dimension 1 was the 3rd: size = 4 = new number of rows
// The dimension 2 was the 1st: size = 2 = new number of columns
// The dimension 3 was the 2sd: size = 1 = new number of pages
y```