en fr

# Library - stdlib

stdlib is a library which extends the native LME functions in the following areas:

The following statement makes available functions defined in stdlib:

```use stdlib
```

## Functions

### circshift

Shift the elements of a matrix in a circular way.

#### Syntax

```use stdlib
B = circshift(A, shift_vert)
B = circshift(A, [shift_vert, shift_hor])
```

#### Description

circshift(A,sv) shifts the rows of matrix A downward by sv rows. The sv bottom rows of the input matrix become the sv top rows of the output matrix. sv may be negative to go the other way around.

circshift(A,[sv,sh]) shifts the rows of matrix A downward by sv rows, and its columns to the right by sh columns. The sv bottom rows of the input matrix become the sv top rows of the output matrix, and the sh rightmost columns become the sh leftmost columns.

### blkdiag

Block-diagonal matrix.

#### Syntax

```use stdlib
X = blkdiag(B1, B2, ...)
```

#### Description

blkdiag(B1,B2,...) creates a block-diagonal matrix with matrix blocks B1, B2, etc. Its input arguments do not need to be square.

#### Example

```use stdlib
blkdiag([1,2;3,4], 5)
1 2 0
3 4 0
0 0 5
blkdiag([1,2], [3;4])
1 2 0
0 0 3
0 0 4
```

diag

### compan

Companion matrix.

#### Syntax

```use stdlib
X = compan(pol)
```

#### Description

compan(pol) gives the companion matrix of polynomial pol, a square matrix whose eigenvalues are the roots of pol.

#### Example

```use stdlib
compan([2,3,4,5])
-1.5  -2.0  -2.5
1.0   0.0   0.0
0.0   1.0   0.0
```

### corrcoef

Correlation coefficients.

#### Syntax

```use stdlib
S = corrcoef(X)
S = corrcoef(X1, X2)
```

#### Description

corrcoef(X) calculates the correlation coefficients of the columns of the m-by-n matrix X. The result is a square n-by-n matrix whose diagonal is 1.

corrcoef(X1,X2) calculates the correlation coefficients of X1 and X2 and returns a 2-by-2 matrix. It is equivalent to corrcoef([X1(:),X2(:)]).

#### Example

```use stdlib
corrcoef([1, 3; 2, 5; 4, 4; 7, 10])
1       0.8915
0.8915  1
corrcoef(1:5, 5:-1:1)
1  -1
-1   1
```

cov

### cumtrapz

Cumulative numeric integration with trapezoidal approximation.

#### Syntax

```use stdlib
S = cumtrapz(Y)
S = cumtrapz(X, Y)
S = cumtrapz(X, Y, dim)
```

#### Description

cumtrapz(Y) calculates an approximation of the cumulative integral of a function given by the samples in Y with unit intervals. The trapezoidal approximation is used. If Y is neither a row nor a column vector, integration is performed along its columns. The result has the same size as Y. The first value(s) is (are) 0.

cumtrapz(X,Y) specifies the location of the samples. A third argument may be used to specify along which dimension the integration is performed.

#### Example

```use stdlib
cumtrapz([2, 3, 5])
0     2.5   6.5
cumtrapz([1, 2, 5], [2, 3, 5])
0     2.5  14.5
```

### fftshift

Shift DC frequency of FFT from beginning to center of spectrum.

#### Syntax

```use stdlib
Y = fftshift(X)
```

#### Description

fftshift(X) shifts halves of vector (1-d) or matrix (2-d) X to move the DC component to the center. It should be used after fft or fft2.

### filter2

Digital 2-d filtering of data.

#### Syntax

```use stdlib
Y = filter2(F, X)
Y = filter2(F, X, shape)
```

#### Description

filter2(F,X) filters matrix X with kernel F with a 2-d correlation. The result has the same size as X.

An optional third argument is passed to conv2 to specify another method to handle the borders.

filter2 and conv2 have three differences: arguments F and X are permuted, filtering is performed with a correlation instead of a convolution (i.e. the kernel is rotated by 180 degrees), and the default method for handling the borders is 'same' instead of 'full'.

### hankel

Hankel matrix.

#### Syntax

```use stdlib
X = hankel(c, r)
```

#### Description

hankel(c,r) creates a Hankel matrix whose first column contains the elements of vector c and whose last row contains the elements of vector r. A Hankel matrix is a matrix whose antidiagonals have the same value. In case of conflict, the first element of r is ignored. The default value of r is a zero vector the same length as c.

#### Example

```use stdlib
hankel(1:3, 3:8)
1  2  3  4  5  6
2  3  4  5  6  7
3  4  5  6  7  8
```

### hist

Histogram.

#### Syntax

```use stdlib
(N, X) = hist(Y)
(N, X) = hist(Y, m)
(N, X) = hist(Y, m, dim)
N = hist(Y, X)
N = hist(Y, X, dim)
```

#### Description

hist(Y) gives the number of elements of vector Y in 10 equally-spaced intervals. A second input argument may be used to specify the number of intervals. The center of the intervals may be obtained in a second output argument.

If Y is an array, histograms are computed along the dimension specified by a third argument or the first non-singleton dimension; the result N has the same size except along that dimension.

When the second argument is a vector, it specifies the centers of the intervals.

#### Example

```use stdlib
(N, X) = hist(logspace(0,1), 5)
N =
45    21    14    11     9
X =
1.9   3.7   5.5   7.3   9.1
```

### ifftshift

Shift DC frequency of FFT from center to beginning of spectrum.

#### Syntax

```use stdlib
Y = ifftshift(X)
```

#### Description

ifftshift(X) shifts halves of vector (1-d) or matrix (2-d) X to move the DC component from the center. It should be used before ifft or ifft2. It reverses the effect of fftshift.

### isreal

Test for a real number.

#### Syntax

```use stdlib
b = isreal(x)
```

#### Description

isreal(x) is true if x is a real scalar or a matrix whose entries are all real.

#### Examples

```use stdlib
isreal([2,5])
true
isreal([2,3+2j])
false
isreal(exp(pi*1j))
true
```

### perms

Array of permutations.

#### Syntax

```use stdlib
M = perms(v)
```

#### Description

perm(v) gives an array whose rows are all the possible permutations of vector v.

#### Example

```use stdlib
perms(1:3)
3  2  1
3  1  2
2  3  1
1  3  2
2  1  3
1  2  3
```

sort

### polyfit

Polynomial fit.

#### Syntax

```use stdlib
pol = polyfit(x, y, n)
```

#### Description

polyfit(x,y,n) calculates the polynomial (given as a vector of descending power coefficients) of order n which best fits the points given by vectors x and y. The least-square algorithm is used.

#### Example

```use stdlib
pol = polyfit(1:5, [2, 1, 4, 5, 2], 3)
pol =
-0.6667  5.5714 -12.7619  9.8000
polyval(pol, 1:5)
1.9429  1.2286  3.6571  5.2286  1.9429
```

### polyvalm

Value of a polynomial with square matrix argument.

#### Syntax

```use stdlib
Y = polyvalm(pol, X)
```

#### Description

polyvalm(pol,X) evaluates the polynomial given by the coefficients pol (in descending power order) with a square matrix argument.

#### Example

```use stdlib
polyvalm([1,2,8],[2,1;0,1])
16  5
0 11
```

polyval

### primes

List of primes.

#### Syntax

```use stdlib
v = primes(n)
```

#### Description

primes(n) gives a row vector which contains the primes up to n.

#### Example

```use stdlib
primes(20)
2  3  5  7 11 13 17 19
```

### sortrows

Sort matrix rows.

#### Syntax

```use stdlib
(S, index) = sortrows(M)
(S, index) = sortrows(M, sel)
(S, index) = sortrows(M, sel, dim)
```

#### Description

sortrows(M) sort the rows of matrix M. The sort order is based on the first column of M, then on the second one for rows with the same value in the first column, and so on.

sortrows(M,sel) use the columns specified in sel for comparing the rows of M. A third argument dim can be used to specify the dimension of the sort: 1 for sorting the rows, or 2 for sorting the columns.

The second output argument of sortrows gives the new order of the rows or columns as a vector of indices.

#### Example

```use stdlib
sortrows([3, 1, 2; 2, 2, 1; 2, 1, 2])
2  1  2
2  2  1
3  1  2
```

sort

### subspace

Angle between two subspaces.

#### Syntax

```use stdlib
theta = subspace(A, B)
```

#### Description

subspace(A,B) gives the angle between the two subspaces spanned by the columns of A and B.

#### Examples

Angle between two vectors in R^2:

```use stdlib
a = [3; 2];
b = [1; 5];
subspace(a, b)
0.7854
```

Angle between the vector [1;1;1] and the plane spanned by [2;5;3] and [7;1;0] in R^3:

```subspace([1;1;1], [2,7;5,1;3,0])
0.2226
```

### toeplitz

Toeplitz matrix.

#### Syntax

```use stdlib
X = toeplitz(c, r)
X = toeplitz(c)
```

#### Description

toeplitz(c,r) creates a Toeplitz matrix whose first column contains the elements of vector c and whose first row contains the elements of vector r. A Toeplitz matrix is a matrix whose diagonals have the same value. In case of conflict, the first element of r is ignored. With one argument, toeplitz gives a symmetric square matrix.

#### Example

```use stdlib
toeplitz(1:3, 1:5)
1  2  3  4  5
2  1  2  3  4
3  2  1  2  3
```

### trapz

Numeric integration with trapezoidal approximation.

#### Syntax

```use stdlib
s = trapz(Y)
s = trapz(X, Y)
s = trapz(X, Y, dim)
```

#### Description

trapz(Y) calculates an approximation of the integral of a function given by the samples in Y with unit intervals. The trapezoidal approximation is used. If Y is an array, integration is performed along the first non-singleton dimension.

trapz(X,Y) specifies the location of the samples. A third argument may be used to specify along which dimension the integration is performed.

#### Example

```use stdlib
trapz([2, 3, 5])
6.5
trapz([1, 2, 5], [2, 3, 5])
14.5
```