*Disponible uniquement en anglais*

Sysquake Pro – Table of Contents

Sysquake for LaTeX – Table of Contents

# Array Functions

### arrayfun

Function evaluation for each element of an array.

#### Syntax

(B1, ...) = arrayfun(fun, A1, ...)

#### Description

`arrayfun(fun,A)` evaluates function `fun` for each
element of numeric array `A`. Each evaluation must give a scalar result
of numeric (or logical or char) type; results are returned as a numeric array the same size as `A`.
First argument is a function reference, an inline function, or the name of a function as a string.

With more than two input arguments, `arrayfun` calls function `fun`
as `feval(fun,A1(i),A2(i),...)`. All array arguments must have the same size,
but their type can be different.

With two output arguments or more, `arrayfun` evaluates function `fun`
with the same number of output arguments and builds a separate array for each output.
Without output argument, `arrayfun` evaluates `fun` without
output argument.

`arrayfun` differs from `cellfun`: all input arguments of
`arrayfun` are arrays of any type (not necessarily cell arrays), and corresponding
elements are provided provided to `fun`. With `map`, input arguments as well
as output arguments are cell arrays.

#### Examples

arrayfun(@isempty, {1, ''; {}, ones(5)}) F T T F map(@isempty, {1, ''; {}, ones(5)}) 2x2 cell array (m, n) = arrayfun(@size, {1, ''; {}, ones(2, 5)}) m = 1 0 0 2 n = 1 0 0 5

#### See also

### cat

Array concatenation.

#### Syntax

cat(dim, A1, A2, ...)

#### Description

`cat(dim,A1,A2,...)` concatenates arrays `A1`, `A2`, etc.
along dimension `dim`. Other dimensions must match. `cat`
is a generalization of the comma and the semicolon inside brackets.

#### Examples

cat(2, [1,2;3,4], [5,6;7,8]) 1 2 5 6 3 4 7 8 cat(3, [1,2;3,4], [5,6;7,8]) 2x2x2 array (:,:,1) = 1 2 3 4 (:,:,2) = 5 6 7 8

#### See also

operator `[]`,
operator `;`,
operator `,`

### cell

Cell array of empty arrays.

#### Syntax

C = cell(n) C = cell(n1,n2,...) C = cell([n1,n2,...])

#### Description

`cell` builds a cell array whose elements are empty arrays `[]`.
The size of the cell array is specified by one integer for a square array, or several
integers (either as separate arguments or in a vector) for a cell array of any size.

#### Example

cell(2, 3) 2x3 cell array

#### See also

### cellfun

Function evaluation for each cell of a cell array.

#### Syntax

A = cellfun(fun, C) A = cellfun(fun, C, ...) A = cellfun(fun, S) A = cellfun(fun, S, ...)

#### Description

`cellfun(fun,C)` evaluates function `fun` for each
cell of cell array `C`. Each evaluation must give a scalar result
of numeric, logical, or character type; results are returned as a non-cell
array the same size as `C`. First argument is a function reference,
an inline function, or the name of a function as a string.

With more than two input arguments, `cellfun` calls function `fun`
as `feval(fun,C{i},other)`, where `C{i}` is each cell
of `C` in turn, and `other` stands for the remaining
arguments of `cellfun`.

The second argument can be a structure array `S` instead of a
cell array. In that case, `fun` is called with `S(i)`.

`cellfun` differs from `map` in two ways: the result
is a non-cell array, and remaining arguments of `cellfun` are provided
directly to `fun`.

#### Examples

cellfun(@isempty, {1, ''; {}, ones(5)}) F T T F map(@isempty, {1, ''; {}, ones(5)}) 2x2 cell array cellfun(@size, {1, ''; {}, ones(5)}, 2) 1 0 0 5

#### See also

### diag

Creation of a diagonal matrix or extraction of the diagonal elements of a matrix.

#### Syntax

M = diag(v) M = diag(v,k) v = diag(M) v = diag(M,k)

#### Description

With a vector input argument, `diag(v)` creates a square diagonal matrix
whose main diagonal is given by `v`. With a second argument, the diagonal
is moved by that amount in the upper right direction for positive values, and in the
lower left direction for negative values.

With a matrix input argument, the main diagonal is extracted and returned as a column vector. A second argument can be used to specify another diagonal.

#### Examples

diag(1:3) 1 0 0 0 2 0 0 0 3 diag(1:3,1) 0 1 0 0 0 0 2 0 0 0 0 3 0 0 0 0 M = magic(3) M = 8 1 6 3 5 7 4 9 2 diag(M) 8 5 2 diag(M,1) 1 7

#### See also

### eye

Identity matrix.

#### Syntax

M = eye(n) M = eye(m,n) M = eye([m,n]) M = eye(..., type)

#### Description

`eye` builds a matrix whose diagonal elements are 1 and other
elements 0. The size of the matrix is specified by one integer for a square matrix,
or two integers (either as two arguments or in a vector of two elements) for a
rectangular matrix.

An additional input argument can be used to specify the type of the result.
It must be the string `'double'`, `'single'`,
`'int8'`, `'int16'`, `'int32'`, `'int64'`,
`'uint8'`, `'uint16'`, `'uint32'`, or `'uint64'`
(64-bit arrays are not supported on all platforms).

#### Examples

eye(3) 1 0 0 0 1 0 0 0 1 eye(2, 3) 1 0 0 0 1 0 eye(2, 'int8') 2x2 int8 array 1 0 0 1

#### See also

### fevalx

Function evaluation with array expansion.

#### Syntax

(Y1,...) = fevalx(fun,X1,...)

#### Description

`(Y1,Y2,...)=fevalx(fun,X1,X2,...)` evaluates function `fun`
with input arguments `X1`, `X2`, etc. Arguments must
be arrays, which are expanded if necessary along singleton dimensions so that all
dimensions match. For instance, three arguments of size 3x1x2, 1x5 and 1x1 are
replicated into arrays of size 3x5x2.
Output arguments are assigned to `Y1`, `Y2`,
etc. Function `fun` is specified
either by its name as a string, by a function reference, or by an inline or anonymous function.

#### Example

fevalx(@plus, 1:5, (10:10:30)') 11 12 13 14 15 21 22 23 24 25 31 32 33 34 35

#### See also

`feval`,
`meshgrid`,
`repmat`,
`inline`,
operator @

### find

Find the indices of the non-null elements of an array.

#### Syntax

ix = find(v) [s1,s2] = find(M) [s1,s2,x] = find(M) ... = find(..., n) ... = find(..., n, dir)

#### Description

With one output argument, `find(v)` returns a vector containing the
indices of the nonzero elements of `v`. `v` can be an array
of any dimension; the indices correspond to the internal storage ordering and
can be used to access the elements with a single subscript.

With two output arguments, `find(M)` returns two vectors containing
the subscripts (row in the first output argument, column in the second output
argument) of the nonzero elements of 2-dim array `M`. To obtain subscripts
for an array of higher dimension, you can convert the single output argument of
`find` to subscripts with `ind2sub`.

With three output arguments, `find(M)` returns in addition the nonzero
values themselves in the third output argument.

With a second input argument `n`, `find` limits the
maximum number of elements found. It searches forward by default; with a third
input argument `dir`, `find` gives the `n` first
nonzero values if `dir` is `'first'` or `'f'`, and the
`n` last nonzero values if `dir` is `'last'` or
`'l'`.

#### Examples

ix = find([1.2,0;0,3.6]) ix = 1 4 [s1,s2] = find([1.2,0;0,3.6]) s1 = 1 2 s2 = 1 2 [s1,s2,x] = find([1.2,0;0,3.6]) s1 = 1 2 s2 = 1 2 x = 1.2 3.6 A = rand(3) A = 0.5599 0.3074 0.5275 0.3309 0.8077 0.3666 0.7981 0.6424 0.6023 find(A > 0.7, 2, 'last') 7 5

#### See also

### flipdim

Flip an array along any dimension.

#### Syntax

B = flipdim(A, dim)

#### Description

`flipdim(A,dim)` gives an array which has the same
size as `A`, but where indices of dimension `dim` are
reversed.

#### Examples

flipdim(cat(3, [1,2;3,4], [5,6;7,8]), 3) 2x2x2 array (:,:,1) = 5 6 7 8 (:,:,2) = 1 2 3 4

#### See also

`fliplr`,
`flipud`,
`rot90`,
`reshape`

### fliplr

Flip an array or a list around its vertical axis.

#### Syntax

A2 = fliplr(A1) list2 = fliplr(list1)

#### Description

`fliplr(A1)` gives an array `A2` which has the same
size as `A1`, but where all columns are placed in reverse order.

`fliplr(list1)` gives a list `list2` which has the
same length as `list1`, but where all top-level elements are placed
in reverse order. Elements themselves are left unchanged.

#### Examples

fliplr([1,2;3,4]) 2 1 4 3 fliplr({1, 'x', {1,2,3}}) {{1,2,3}, 'x', 1}

#### See also

`flipud`,
`flipdim`,
`rot90`,
`reshape`

### flipud

Flip an array upside-down.

#### Syntax

A2 = flipud(A1)

#### Description

`flipud(A1)` gives an array `A2` which has the same
size as `A1`, but where all lines are placed in reverse order.

#### Example

flipud([1,2;3,4]) 3 4 1 2

#### See also

`fliplr`,
`flipdim`,
`rot90`,
`reshape`

### ind2sub

Conversion from single index to row/column subscripts.

#### Syntax

(i, j, ...) = ind2sub(size, ind)

#### Description

`ind2sub(size,ind)` gives the subscripts of the element which
would be retrieved from an array whose size is specified by `size`
by the single index `ind`.
`size` must be either a scalar for square matrices or a vector of
two elements or more for arrays.
`ind` can be an array; the result is calculated separately for each element
and has the same size.

#### Example

M = [3, 6; 8, 9]; M(3) 8 (i, j) = ind2sub(size(M), 3) i = 2 j = 1 M(i, j) 8

#### See also

### interp1

1D interpolation.

#### Syntax

yi = interp1(x, y, xi) yi = interp1(x, y, xi, method) yi = interp1(y, xi) yi = interp1(y, xi, method) yi = interp1(..., method, extraval)

#### Description

`interp1(x,y,xi)` interpolates data along one dimension. Input
data are defined by vector `y`, where element `y(i)`
corresponds to coordinates `x(i)`. Interpolation is performed at
points defined in vector `xi`; the result is a vector of the same
size as `xi`.

If `y` is an array, interpolation is performed along dimension
1 (i.e. along its columns), and `size(y,1)` must be equal to
`length(x)`. Then if `xi` is a vector, interpolation
is performed at the same points for each remaining dimensions of `y`,
and the result is an array of size `[length(xi),size(y)(2:end)]`;
if `xi` is an array, all sizes must match `y` except for
the first one.

If `x` is missing, it defaults to `1:size(y,1)`.

The default interpolation method is piecewise linear. An additional input argument can be provided to specify it with a string (only the first character is considered):

Argument | Meaning |
---|---|

'0' or 'nearest' | nearest value |

'<' | lower coordinate |

'>' | higher coordinate |

'1' or 'linear' | piecewise linear |

'3' or 'cubic' | piecewise cubic |

'p' or 'pchip' | pchip |

Cubic interpolation gives continuous values and first derivatives, and null second derivatives at end points. Pchip (piecewise cubic Hermite interpolation) also gives continuous values and first derivatives, but guarantees that the interpolant stays within the limits of the data in each interval (in particular monotonicity is preserved) at the cost of larger second derivatives.

With vectors, `interp1` produces the same result as `interpn`;
vector orientations do not have to match, though.

When the method is followed by a scalar number `extraval`, that
value is assigned to all values outside the range defined by `x`
(i.e. extrapolated values). The default is NaN.

#### Examples

One-dimension interpolation:

interp1([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7]) nan 0.2000 0.3000 0.8333 interp1([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7], '0') nan 0.2000 0.2000 1.0000

Interpolation of multiple values:

t = 0:10; y = [sin(t'), cos(t')]; tnew = 0:0.4:8; ynew = interp1(t, y, tnew) ynew = 0.0000 1.0000 0.3366 0.8161 ... 0.8564 0.2143 0.9894 -0.1455

#### See also

### interpn

Multidimensional interpolation.

#### Syntax

Vi = interpn(x1, ..., xn, V, xi1, ..., xin) Vi = interpn(x1, ..., xn, V, xi1, ..., xin, method) Vi = interpn(..., method, extraval)

#### Description

`interpn(x1,...,xn,V,xi1,...,xin)` interpolates data in a space
of `n` dimensions. Input data are defined by array `V`,
where element `V(i,j,...)` corresponds to coordinates `x1(i)`,
`x2(j)`, etc. Interpolation is performed for each coordinates defined
by arrays `xi1`, `xi2`, etc., which must all have the same
size; the result is an array of the same size.

Length of vectors `x1`, `x2`, ... must match the
size of `V` along the corresponding dimension. Vectors `x1`,
`x2`, ... must be sorted (monotonically increasing or decreasing),
but they do not have to be spaced uniformly. Interpolated points outside the input volume
are set to nan.
Input and output data can be complex. Imaginary parts of coordinates are ignored.

The default interpolation method is multilinear. An additional input argument can be provided to specify it with a string (only the first character is considered):

Argument | Meaning |
---|---|

'0' or 'nearest' | nearest value |

'<' | lower coordinates |

'>' | higher coordinates |

'1' or 'linear' | multilinear |

Method `'<'` takes the sample where each coordinate has its index as large as
possible, lower or equal to the interpolated value, and smaller than the last coordinate.
Method `'>'` takes the
sample where each coordinate has its index greater or equal to the interpolated value.

When the method is followed by a scalar number `extraval`, that
value is assigned to all values outside the input volume
(i.e. extrapolated values). The default is NaN.

#### Examples

One-dimension interpolation:

interpn([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7]) nan 0.2000 0.3000 0.8333 interpn([1, 2, 5, 8], [0.1, 0.2, 0.5, 1], [0, 2, 3, 7], '0') nan 0.2000 0.2000 1.0000

Three-dimension interpolation:

D = cat(3,[0,1;2,3],[4,5;6,7]); interpn([0,1], [0,1], [0,1], D, 0.2, 0.7, 0.5) 3.1000

Image rotation (we define original coordinates between -0.5 and 0.5 in vector `c`
and arrays `X` and `Y`, and the image as a linear
gradient between 0 and 1):

c = -0.5:0.01:0.5; X = repmat(c, 101, 1); Y = X'; phi = 0.2; Xi = cos(phi) * X - sin(phi) * Y; Yi = sin(phi) * X + cos(phi) * Y; D = 0.5 + X; E = interpn(c, c, D, Xi, Yi); E(isnan(E)) = 0.5;

#### See also

### intersect

Set intersection.

#### Syntax

c = intersect(a, b) (c, ia, ib) = intersect(a, b)

#### Description

`intersect(a,b)` gives the intersection of sets `a` and
`b`, i.e. it gives the set of members of both sets `a` and `b`.
Sets are any type of numeric, character or logical arrays,
or lists or cell arrays of character strings. Multiple elements of input arguments
are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that
if `(c,ia,ib)=intersect(a,b)`, then `c` is `a(ia)`
as well as `b(ib)`.

#### Example

a = {'a','bc','bbb','de'}; b = {'z','bc','aa','bbb'}; (c, ia, ib) = intersect(a, b) c = {'bbb','bc'} ia = 3 2 ib = 4 2 a(ia) {'bbb','bc'} b(ib) {'bbb','bc'}

Set exclusive or can also be computed as the union of `a` and
`b` minus the intersection of `a` and `b`:

setdiff(union(a, b), intersect(a, b)) {'a','aa','de','z'}

#### See also

`unique`,
`union`,
`setdiff`,
`setxor`,
`ismember`

### inthist

Histogram of an integer array.

#### Syntax

h = inthist(A, n)

#### Description

`inthist(A,n)` computes the histogram of the elements of integer array
`A` between 0 and n-1. `A` must have an integer type (int8/16/32/64
or uint8/16/32/64). The result is a row vector `h` of length `n`,
where `h(i)` is the number of elements in `A` with value
`i-1`.

#### Example

A = map2int(rand(100), 0, 1, 'uint8'); h = inthist(A, 10) h = 37 31 34 34 32 35 38 36 36 32

#### See also

### ipermute

Inverse permutation of the dimensions of an array.

#### Syntax

B = ipermute(A, perm)

#### Description

`ipermute(A,perm)` returns an array with the same elements as
`A`, but where dimensions are permuted according to the vector of
dimensions `perm`. It performs the inverse permutation of `permute`.
`perm` must contain integers from 1 to `n`; dimension `i`
in `A` becomes dimension `perm(i)` in the result.

#### Example

size(ipermute(rand(3,4,5), [2,3,1])) 5 3 4

#### See also

### isempty

Test for empty array, list or struct.

#### Syntax

b = isempty(A) b = isempty(list) b = isempty(S)

#### Description

`isempty(obj)` gives true if `obj` is the empty array `[]`
of any type (numeric, char, logical or cell array) or the empty struct, and false otherwise.

#### Examples

isempty([]) true isempty(0) false isempty('') true isempty({}) true isempty({{}}) false isempty(struct) true

#### See also

### iscell

Test for cell arrays.

#### Syntax

b = iscell(X)

#### Description

`iscell(X)` gives true if `X` is a cell array or
a list, and false otherwise.

#### Examples

iscell({1;2}) true iscell({1,2}) true islist({1;2}) false

#### See also

### ismember

Test for set membership.

#### Syntax

b = ismember(m, s) (b, ix) = ismember(m, s)

#### Description

`ismember(m,s)` tests if elements of array `m` are members
of set `s`. The result is a logical array the same size as `m`;
each element is `true` if the corresponding element of `m`
is a member of `s`, or false otherwise. `m` must be a numeric
array or a cell array, matching type of set `s`.

With a second output argument `ix`, `ismember` also gives the
index of the corresponding element of `m` in `s`, or 0 if the
element is not a member of `s`.

#### Example

s = {'a','bc','bbb','de'}; m = {'d','a','x';'de','a','z'}; (b, ix) = ismember(m, s) b = F T F T T F ix = 0 1 0 4 1 0

#### See also

`intersect`,
`union`,
`setdiff`,
`setxor`

### length

Length of a vector or a list.

#### Syntax

n = length(v) n = length(list)

#### Description

`length(v)` gives the length of vector `v`.
`length(A)` gives the number of elements along the largest dimension
of array `A`. `length(list)` gives
the number of elements in a list.

#### Examples

length(1:5) 5 length((1:5)') 5 length(ones(2,3)) 3 length({1, 1:6, 'abc'}) 3 length({{}}) 1

#### See also

### linspace

Sequence of linearly-spaced elements.

#### Syntax

v = linspace(x1, x2) v = linspace(x1, x2, n)

#### Description

`linspace(x1,x2)` produces a row vector of 50 values spaced
linearly from `x1` to `x2` inclusive. With a third
argument, `linspace(x1,x2,n)` produces a row vector of `n`
values.

#### Examples

linspace(1,10) 1.0000 1.1837 1.3673 ... 9.8163 10.0000 linspace(1,2,6) 1.0 1.2 1.4 1.6 1.8 2.0

#### See also

### logspace

Sequence of logarithmically-spaced elements.

#### Syntax

v = logspace(x1, x2) v = logspace(x1, x2, n)

#### Description

`logspace(x1,x2)` produces a row vector of 50 values
spaced logarithmically from `10^x1` to `10^x2` inclusive. With a third
argument, `logspace(x1,x2,n)` produces a row vector of `n`
values.

#### Example

logspace(0,1) 1.0000 1.0481 1.0985 ... 9.1030 9.5410 10.0000

#### See also

### magic

Magic square.

#### Syntax

M = magic(n)

#### Description

A magic square is a square array of size n-by-n which contains each integer
between 1 and `magic(n)` returns magic square of size n-by-n.

There is no 2-by-2 magic square. If the size is 2, the matrix [1,3;4,2] is returned instead.

#### Example

magic(3) 8 1 6 3 5 7 4 9 2

#### See also

### meshgrid

Arrays of X-Y coordinates.

#### Syntax

(X, Y) = meshgrid(x, y) (X, Y) = meshgrid(x)

#### Description

`meshgrid(x,y)` produces two arrays of x and y coordinates suitable for
the evaluation of a function of two variables. The input argument `x`
is copied to the rows of the first output argument, and the input argument `y`
is copied to the columns of the second output argument, so that both arrays have the same
size. `meshgrid(x)` is equivalent to `meshgrid(x,x)`.

#### Example

(X, Y) = meshgrid(1:5, 2:4) X = 1 2 3 4 5 1 2 3 4 5 1 2 3 4 5 Y = 2 2 2 2 2 3 3 3 3 3 4 4 4 4 4 Z = atan2(X, Y) Z = 0.4636 0.7854 0.9828 1.1071 1.1903 0.3218 0.5880 0.7854 0.9273 1.0304 0.2450 0.4636 0.6435 0.7854 0.8961

#### See also

### ndgrid

Arrays of N-dimension coordinates.

#### Syntax

(X1, ..., Xn) = ndgrid(x1, ..., xn) (X1, ..., Xn) = ndgrid(x)

#### Description

`ndgrid(x1,...,xn)` produces `n` arrays of n dimensions.
Array `i` is obtained by reshaping input argument `i` as a vector along
dimension `i` and replicating it along all other dimensions to match the
length of other input vectors. All output arguments have the same size.

With one input argument, `ndgrid` reuses it to match the number
of output arguments.

`(Y,X)=ndgrid(y,x)` is equivalent to `(X,Y)=meshgrid(x,y)`.

#### Example

(X1, X2) = ndgrid(1:3) X1 = 1 1 1 2 2 2 3 3 3 X2 = 1 2 3 1 2 3 1 2 3

#### See also

### ndims

Number of dimensions of an array.

#### Syntax

n = ndims(A)

#### Description

`ndims(A)` returns the number of dimensions of array
`A`, which is at least 2. Scalars, row and column vectors, and matrices
have 2 dimensions.

#### Examples

ndims(magic(3)) 2 ndims(rand(3,4,5)) 3

#### See also

`size`,
`squeeze`,
`permute`,
`ipermute`

### nnz

Number of nonzero elements.

#### Syntax

n = nnz(A)

#### Description

`nnz(A)` returns the number of nonzero elements of array `A`.
Argument `A` must be a numeric, char or logical array.

#### Examples

nnz(-2:2) 4 nnz(magic(3) > 3) 6

#### See also

### num2cell

Conversion from numeric array to cell array.

#### Syntax

C = num2cell(A) C = num2cell(A, dims)

#### Description

`num2cell(A)` creates a cell array the same size as numeric array `A`.
The value of each cell is the corresponding elements of `A`.

`num2cell(A,dims)` cuts array `A` along the dimensions *not* in
`dims` and creates a cell array with the result. Dimensions of cell array are the same
as dimensions of `A` for dimensions not in `dims`, and 1 for dimensions in
`dims`; dimensions of cells are the same as dimensions of `A`
for dimensions in `dims`, and 1 for dimensions not in `dims`.

Argument `A` can be a numeric array of any dimension and class,
a logical array, or a char array.

#### Examples

num2cell([1, 2; 3, 4]) {1, 2; 3, 4} num2cell([1, 2; 3, 4], 1) {[1; 3], [2; 4]} num2cell([1, 2; 3, 4], 2) {[1, 2]; [3, 4]}

#### See also

### numel

Number of elements of an array.

#### Syntax

n = numel(A)

#### Description

`numel(A)` gives the number of elements of array `A`.
It is equivalent to `prod(size(A))`.

#### Examples

numel(1:5) 5 numel(ones(2, 3)) 6 numel({1, 1:6; 'abc', []}) 4 numel({2, 'vwxyz'}) 2

#### See also

### ones

Array of ones.

#### Syntax

A = ones(n) A = ones(n1, n2, ...) A = ones([n1, n2, ...]) A = ones(..., type)

#### Description

`ones` builds an array whose elements are 1. The size of the array
is specified by one integer for a square matrix, or several integers (either as separate
arguments or in a vector) for an array of any size.

An additional input argument can be used to specify the type of the result.
It must be the string `'double'`, `'single'`,
`'int8'`, `'int16'`, `'int32'`, `'int64'`,
`'uint8'`, `'uint16'`, `'uint32'`, or `'uint64'`
(64-bit arrays are not supported on all platforms).

#### Examples

ones(2,3) 1 1 1 1 1 1 ones(2, 'int32') 2x2 int32 array 1 1 1 1

#### See also

`zeros`,
`eye`,
`rand`,
`randn`,
`repmat`

### permute

Permutation of the dimensions of an array.

#### Syntax

B = permute(A, perm)

#### Description

`permute(A,perm)` returns an array with the same elements as
`A`, but where dimensions are permuted according to the vector of
dimensions `perm`. It is a generalization of the matrix transpose operator.
`perm` must contain integers from 1 to `n`; dimension `perm(i)`
in `A` becomes dimension `i` in the result.

#### Example

size(permute(rand(3,4,5), [2,3,1])) 4 5 3

#### See also

`ndims`,
`squeeze`,
`ipermute`,
`num2cell`

### rand

Uniformly-distributed random number.

#### Syntax

x = rand A = rand(n) A = rand(n1, n2, ...) A = rand([n1, n2, ...]) A = rand(..., type) rand('seed', s);

#### Description

`rand` builds a scalar pseudo-random number uniformly distributed
between 0 and 1. The lower bound 0 may be reached, but the upper bound 1 is never.
The default generator is based on a scalar 64-bit seed, which theoretically
has a period of 2^64-2^32 numbers. This seed can be set with the arguments
`rand('seed',s)`, where `s` is a scalar. `rand('seed',s)`
returns the empty array [] as output argument. To discard it, the statement should be
followed by a semicolon. The generator can be changed with `rng`.

`rand(n)`, `rand(n1,n2,...)` and `rand([n1,n2,...])`
return an n-by-n square array or an array of arbitrary size whose elements are
pseudo-random numbers uniformly distributed between 0 and 1.

An additional input argument can be used to specify the type of the result,
`'double'` (default) or `'single'`.
With the special value `'raw'`, `rand` returns an unscaled integer
result of type double which corresponds to the uniform output of the random generator before
it is mapped to the range between 0 and 1. The scaling factor can be retrieved in the
field `rawmax` of the structure returned by `rng`.

#### Examples

rand 0.2361 rand(1, 3) 0.6679 0.8195 0.2786 rand('seed',0); rand 0.2361

#### See also

### randi

Uniformly-distributed integer random number.

#### Syntax

x = randi(nmax) x = randi(range) M = randi(..., n) M = randi(..., n1, n2, ...) M = randi(..., [n1, n2, ...]) M = randi(..., class)

#### Description

`randi(nmax)` produces a scalar pseudo-random integer number uniformly
distributed between 1 and `nmax`. `randi(range)`, where `range`
is a two-element vector `[nmin,nmax]`, produces a scalar pseudo-random
integer number uniformly distributed between `nmin` and `nmax`.

With more numeric input arguments, `randi` produces arrays of
pseudo-random integer numbers. `randi(range,n)` produces an n-by-n
square array, and `randi(range,[n1,n2,...])` or `randi(range,n1,n2,...)`
produces an array of the specified size.

The number class of the result can be specified with a final string argument.
The default is `'double'`.

#### Examples

randi(10) 3 randi(10, [1, 5]) 3 4 6 8 1 randi([10,15], [1, 5]) 12 14 13 10 13 randi(8, [1, 5], 'uint8') 1x5 uint8 array 3 4 5 7 2

#### See also

### randn

Normally-distributed random number

#### Syntax

x = randn A = randn(n) A = randn(n1, n2, ...) A = randn([n1, n2, ...]) A = randn(..., type) randn('seed', s);

#### Description

`randn` builds a scalar pseudo-random number chosen from a normal
distribution with zero mean and unit variance.
The default generator is based on a scalar 64-bit seed, which theoretically
has a period of 2^64-2^32 numbers. This seed can be set with the arguments
`randn('seed',s)`, where `s` is a scalar. The seed is the
same as the seed of `rand` and `rng`.
`randn('seed',s)` returns the empty array [] as output argument. To
discard it, the statement should be followed by a semicolon. The generator can be
changed with `rng`.

`randn(n)`, `randn(n1,n2,...)` and `randn([n1,n2,...])`
return an n-by-n square array or an array of arbitrary size whose elements are
pseudo-random numbers chosen from a normal distribution.

An additional input argument can be used to specify the type of the result.
It must be the string `'double'` (default) or `'single'`.

#### Examples

randn 1.5927 randn(1, 3) 0.7856 0.6489 -0.8141 randn('seed',0); randn 1.5927

#### See also

### repmat

Replicate an array.

#### Syntax

B = repmat(A, n) B = repmat(A, m, n) B = repmat(A, [n1,...])

#### Description

`repmat` creates an array with multiple copies of its first argument.
It can be seen as an extended version of `ones`, where 1 is replaced by
an arbitrary array.

With 3 input arguments, `repmat(A,m,n)` replicates array `A`
`m` times vertically and `n` times horizontally. The type of the first
argument (number, character, logical, cell, or structure array) is preserved.

With two input arguments, `repmat(A,n)` produces the same result as
`repmat(A,n,n)`.

With a vector as second argument, the array can be replicated along more than two
dimensions; `repmat(A,m,n)` produces the same result as
`repmat(A,[m,n])`.

#### Examples

repmat([1,2;3,4], 1, 2) 1 2 1 2 3 4 3 4 repmat('abc', 3) abcabcabc abcabcabc abcabcabc

#### See also

`zeros`,
`ones`,
operator `:`,
`kron`,
`replist`

### reshape

Rearrange the elements of an array to change its shape.

#### Syntax

A2 = reshape(A1) A2 = reshape(A1, n1, n2, ...) A2 = reshape(A1, [n1, n2, ...])

#### Description

`reshape(A1)` gives a column vector with all the elements of
array `A1`. If `A1` is a variable,
`reshape(A1)` is the same as `A1(:)`.

`reshape(A1,n1,n2,...)` or `reshape(A1,[n1,n2,...])` changes the
dimensions of array `A1` so that the result has `m` rows
and `n` columns. `A1` must have `n1*n2*...` elements;
read row-wise, both `A1` and the result have the same elements.

When dimensions are given as separate elements, one of them can be replaced
with the empty array `[]`; it is replaced by the value such that
the number of elements of the result matches the size of input array.

**Remark:** code should not rely on the internal data layout.
Array elements are currently stored row-wise, but this may change in the future.
`reshape` will remain consistant with indexing, though;
`reshape(A,s)(i)==A(i)` for any compatible size `s`.

#### Example

reshape([1,2,3;10,20,30], 3, 2) 1 2 3 10 20 30 reshape(1:12, 3, []) 1 2 3 4 5 6 7 8 9 10 11 12

#### See also

### rng

State of random number generator.

#### Syntax

rng(type) rng(seed) rng(seed, type) rng(state) state = rng

#### Description

Random (actually pseudo-random) number generators produce sequences of numbers whose
statistics make them difficult to distinguish from true random numbers. They are used by
functions `rand`, `randi`, `randn` and `random`.
They are characterized by a type string and a state.

With a numeric input argument, `rng(seed)` sets the state based on a seed.
The state is usually an array of unsigned 32-bit integer numbers. `rng` uses the
seed to produce an internal state which is valid for the type of random number generator.
The default seed is 0.

With a string input argument, `rng(type)` sets the type of the random number
generator and resets the state to its initial value (default seed). The following types
are recognized:

`'original'`- Original generator used until LME 6.
`'mcg16807'`- Multiplicative congruential generator. The state is defined by
`s(i+1)=mod(a*s(i),m)`with`a=7^5`and`m=2^31-1`, and the generated value is`s(i)/m`. `'mwc'`- Concatenation of two 16-bit multiply-with-carry generators. The period is about
`2^60`. `'kiss'`or`'default'`- Combination of mwc, a 3-shift register, and a congruential generator. The period
is about
`2^123`.

With two input arguments, `rng(seed,type)` sets both the seed and the
type of the random number generator.

With an output argument, `state=rng` gets the current state, which can be
restored later by calling `rng(state)`. The state is a structure.

#### Examples

rng(123); R = rand(1,2) R = 0.2838 0.4196 s = rng s = type: 'original' state: real 2x1 rawmax: 4294967296 R = rand R = 0.5788 rng(s) R = rand R = 0.5788

#### Reference

The MWC and KISS generators are described in George Marsaglia,
*Random numbers for C: The END?*, Usenet, sci.stat.math, 20 Jan 1999.

#### See also

### rot90

Array rotation.

#### Syntax

A2 = rot90(A1) A2 = rot90(A1, k)

#### Description

`rot90(A1)` rotates array `A1` 90 degrees
counter-clockwise; the top left element of `A1` becomes the bottom
left element of `A2`. If `A1` is an array with more
than two dimensions, each plane corresponding to the first two dimensions
is rotated.

In `rot90(A1,k)`, the second argument is the number of times the
array is rotated 90 degrees counter-clockwise. With
`k = 2`, the array is rotated by 180 degrees; with
`k = 3` or `k = -1`, the array is
rotated by 90 degrees clockwise.

#### Examples

rot90([1,2,3;4,5,6]) 3 6 2 5 1 4 rot90([1,2,3;4,5,6], -1) 4 1 5 2 6 3 rot90([1,2,3;4,5,6], -1) 6 5 4 3 2 1 fliplr(flipud([1,2,3;4,5,6])) 6 5 4 3 2 1

#### See also

### setdiff

Set difference.

#### Syntax

c = setdiff(a, b) (c, ia) = setdiff(a, b)

#### Description

`setdiff(a,b)` gives the difference between sets `a` and
`b`, i.e. the set of members of set `a` which do not belong
to `b`. Sets are any type of numeric, character or logical arrays,
or lists or cell arrays of character strings. Multiple elements of input arguments
are considered as single members; the result is always sorted and has unique elements.

The optional second output argument is a vector of indices such that
if `(c,ia)=setdiff(a,b)`, then `c` is `a(ia)`.

#### Example

a = {'a','bc','bbb','de'}; b = {'z','bc','aa','bbb'}; (c, ia) = setdiff(a, b) c = {'a','de'} ia = 1 4 a(ia) {'a','de'}

#### See also

`unique`,
`union`,
`intersect`,
`setxor`,
`ismember`

### setxor

Set exclusive or.

#### Syntax

c = setxor(a, b) (c, ia, ib) = setxor(a, b)

#### Description

`setxor(a,b)` performs an exclusive or operation between sets `a` and
`b`, i.e. it gives the set of members of sets `a` and `b`
which are not members of the intersection of `a` and `b`.
Sets are any type of numeric, character or logical arrays,
or lists or cell arrays of character strings. Multiple elements of input arguments
are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that
if `(c,ia,ib)=setxor(a,b)`, then `c` is the union of `a(ia)`
and `b(ib)`.

#### Example

a = {'a','bc','bbb','de'}; b = {'z','bc','aa','bbb'}; (c, ia, ib) = setxor(a, b) c = {'a','aa','de','z'} ia = 1 4 ib = 3 1 union(a(ia),b(ib)) {'a','aa','de','z'}

Set exclusive or can also be computed as the union of `a` and
`b` minus the intersection of `a` and `b`:

setdiff(union(a, b), intersect(a, b)) {'a','aa','de','z'}

#### See also

`unique`,
`union`,
`intersect`,
`setdiff`,
`ismember`

### size

Size of an array.

#### Syntax

v = size(A) (m, n) = size(A) m = size(A, i)

#### Description

`size(A)` returns the number of rows and the number of elements
along each dimension of array
`A`, either in a row vector or as scalars if there are two output
arguments or more.

`size(A,i)` gives the number of elements in array `A`
along dimension `i`:
`size(A,1)` gives the number of rows and
`size(A,2)` the number of columns.

#### Examples

M = ones(3, 5); size(M) 3 5 (m, n) = size(M) m = 3 n = 5 size(M, 1) 3 size(M, 2) 5

#### See also

### sort

Array sort.

#### Syntax

(A_sorted, ix) = sort(A) (A_sorted, ix) = sort(A, dim) (A_sorted, ix) = sort(A, dir) (A_sorted, ix) = sort(A, dim, dir) (list_sorted, ix) = sort(list) (list_sorted, ix) = sort(list, dir)

#### Description

`sort(A)` sorts separately the elements of each column of
array `A`, or the elements of `A` if it is a row vector.
The result has the same size as `A`. Elements are sorted in ascending
order, with NaNs at the end. For complex arrays, numbers are sorted by magnitude.

The optional second output
argument gives the permutation array which transforms `A` into the
sorted array. It can be used to reorder elements in another array or to sort the
rows of a matrix with respect to one of its columns, as shown in the last example
below. Order of consecutive identical elements is preserved.

If a second numeric argument `dim` is provided, the sort is performed along
dimension `dim` (columns if `dim` is 1, rows if 2, etc.)

An additional argument can specify the ordering direction. It must be the
string `'ascending'` (or `'a'`) for ascending order, or
`'descending'` (or `'d'`) for descending order. In both
cases, NaNs are moved to the end.

`sort(list)` sorts the elements of a list, which must be strings.
Cell arrays are sorted like lists, not column-wise like numeric arrays. The second
output argument is a row vector. The direction can be specified with a second
input argument.

#### Examples

sort([3,6,2,3,9,1,2]) 1 2 2 3 3 6 9 sort([2,5,3;nan,4,2;6,1,1]) 2 1 1 6 4 2 nan 5 3 sort([2,5,3;nan,4,2;6,1,1], 'd') 6 5 3 2 4 2 nan 1 1 sort({'def', 'abcd', 'abc'}) {'abc', 'abcd', 'def'}

To sort the rows of an array after the first column, one can obtain the permutation vector by sorting the first column, and use it as subscripts on the array rows:

M = [2,4; 5,1; 3,9; 4,0] 2 4 5 1 3 9 4 0 (Ms, ix) = sort(M(:,1)); M(ix,:) 2 4 3 9 4 0 5 1

#### Algorithm

Shell sort.

#### See also

### squeeze

Suppression of singleton dimensions of an array.

#### Syntax

B = squeeze(A)

#### Description

`squeeze(A)` returns an array with the same elements as
`A`, but where dimensions equal to 1 are removed. The result has
at least 2 dimensions; row and column vectors keep their dimensions.

#### Examples

size(squeeze(rand(1,2,3,1,4))) 2 3 4 size(squeeze(1:5)) 1 5

#### See also

### sub2ind

Conversion from row/column subscripts to single index.

#### Syntax

ind = sub2ind(size, i, j) ind = sub2ind(size, i, j, k, ...)

#### Description

`sub2ind(size,i,j)` gives the single index which can be used
to retrieve the element corresponding to the `i`:th row and the
`j`:th column of an array whose size is specified by `size`.
`size` must be either a scalar for square matrices or a vector of
two elements or more for other arrays.
If `i` and `j` are arrays, they must have the same
size: the result is calculated separately for each element and has the same size.

`sub2ind` also accepts sizes and subscripts for arrays with more than
2 dimensions. The number of indices must match the length of `size`.

#### Example

M = [3, 6; 8, 9]; M(2, 1) 8 sub2ind(size(M), 2, 1) 7 M(3) 8

#### See also

### tril

Extraction of the lower triangular part of a matrix.

#### Syntax

L = tril(M) L = tril(M,k)

#### Description

`tril(M)` extracts the lower triangular part of a matrix; the result is a matrix
of the same size where all the elements
above the main diagonal are set to zero. A second argument can be used to specify another
diagonal: 0 is the main diagonal, positive values are above and negative values below.

#### Examples

M = magic(3) M = 8 1 6 3 5 7 4 9 2 tril(M) 8 0 0 3 5 0 4 9 2 tril(M,1) 8 1 0 3 5 7 4 9 2

#### See also

### triu

Extraction of the upper triangular part of a matrix.

#### Syntax

U = triu(M) U = triu(M,k)

#### Description

`tril(M)` extracts the upper triangular part of a matrix; the result is a matrix
of the same size where all the elements
below the main diagonal are set to zero. A second argument can be used to specify another
diagonal; 0 is the main diagonal, positive values are above and negative values below.

#### Examples

M = magic(3) M = 8 1 6 3 5 7 4 9 2 triu(M) 8 1 6 0 5 7 0 0 2 triu(M,1) 0 1 6 0 0 7 0 0 0

#### See also

### union

Set union.

#### Syntax

c = union(a, b) (c, ia, ib) = union(a, b)

#### Description

`union(a,b)` gives the union of sets `a` and
`b`, i.e. it gives the set of members of sets `a` or `b`
or both.
Sets are any type of numeric, character or logical arrays,
or lists or cell arrays of character strings. Multiple elements of input arguments
are considered as single members; the result is always sorted and has unique elements.

The optional second and third output arguments are vectors of indices such that
if `(c,ia,ib)=union(a,b)`, then elements of `c` are the
elements of `a(ia)` or `b(ib)`; the intersection of
`a(ia)` and `b(ib)` is empty.

#### Example

a = {'a','bc','bbb','de'}; b = {'z','bc','aa','bbb'}; (c, ia, ib) = union(a, b) c = {'a','aa','bbb','bc','de','z'} ia = 1 3 2 4 ib = 3 1 a(ia) {'a','bbb','bc','de'} b(ib) {'aa','z'}

Set exclusive or can also be computed as the union of `a` and
`b` minus the intersection of `a` and `b`:

setdiff(union(a, b), intersect(a, b)) {'a','aa','de','z'}

#### See also

`unique`,
`intersect`,
`setdiff`,
`setxor`,
`ismember`

### unique

Keep unique elements.

#### Syntax

v2 = unique(v1) list2 = unique(list1) (b, ia, ib) = unique(a)

#### Description

With an array argument, `unique(v1)` sorts its elements
and removes duplicate elements. Unless `v1` is a row vector, `v1`
is considered as a column vector.

With an argument which is a list of strings, `unique(list)` sorts its elements
and removes duplicate elements.

The optional second output argument is set to a vector of indices such that
if `(b,ia)=unique(a)`, then `b` is `a(ia)`.

The optional third output argument is set to a vector of indices such that
if `(b,ia,ib)=unique(a)`, then `a` is `b(ib)`.

#### Examples

(b,ia,ib) = unique([4,7,3,8,7,1,3]) b = 1 3 4 7 8 ia = 6 3 1 2 4 ib = 3 4 2 5 4 1 2 unique({'def', 'ab', 'def', 'abc'}) {'ab', 'abc', 'def'}

#### See also

`sort`,
`union`,
`intersect`,
`setdiff`,
`setxor`,
`ismember`

### unwrap

Unwrap angle sequence.

#### Syntax

a2 = unwrap(a1) a2 = unwrap(a1, tol) A2 = unwrap(A1, tol, dim)

#### Description

`unwrap(a1)`, where `a1` is a vector of angles in radians,
returns a vector `a2` of the same length, with the same values modulo

With two input arguments, `unwrap(a1,tol)` reduces the difference between
two consecutive values only if it is larger (in absolute value) than `tol`.
If `tol` is smaller than `[]`, the default value of

With three input arguments, `unwrap(A1,tol,dim)` operates along
dimension `dim`. The result is an array of the same size as `A1`.
The default dimension for arrays is 1.

#### Example

unwrap([0, 2, 4, 6, 0, 2]) 0.00 2.00 4.00 6.00 6.28 8.28

#### See also

### zeros

Zero array.

#### Syntax

A = zeros(n) A = zeros(n1,n2,...) A = zeros([n1,n2,...]) A = zeros(..., type)

#### Description

`zeros` builds an array whose elements are 0. The size of the array
is specified by one integer for a square matrix, or several integers (either as separate
arguments or in a vector) for an array of any size.

An additional input argument can be used to specify the type of the result.
It must be the string `'double'`, `'single'`,
`'int8'`, `'int16'`, `'int32'`, `'int64'`,
`'uint8'`, `'uint16'`, `'uint32'`, or `'uint64'`
(64-bit arrays are not supported on all platforms).

#### Examples

zeros([2,3]) 0 0 0 0 0 0 zeros(2) 0 0 0 0 zeros(1, 5, 'uint16') 1x5 uint16 array 0 0 0 0 0