Next: Special Utility Matrices, Previous: Finding Elements and Checking Conditions, Up: Matrix Manipulation [Contents][Index]

- Function File:
**fliplr***(*`x`) Flip array left to right.

Return a copy of

`x`with the order of the columns reversed. In other words,`x`is flipped left-to-right about a vertical axis. For example:fliplr ([1, 2; 3, 4]) ⇒ 2 1 4 3

- Function File:
**flipud***(*`x`) Flip array upside down.

Return a copy of

`x`with the order of the rows reversed. In other words,`x`is flipped upside-down about a horizontal axis. For example:flipud ([1, 2; 3, 4]) ⇒ 3 4 1 2

- Function File:
**flip***(*`x`) - Function File:
**flip***(*`x`,`dim`) Flip array across dimension

`dim`.Return a copy of

`x`flipped about the dimension`dim`.`dim`defaults to the first non-singleton dimension. For example:flip ([1 2 3 4]) ⇒ 4 3 2 1 flip ([1; 2; 3; 4]) ⇒ 4 3 2 1 flip ([1 2; 3 4]) ⇒ 3 4 1 2 flip ([1 2; 3 4], 2) ⇒ 2 1 4 3

**See also:**fliplr, flipud, rot90, rotdim, permute, transpose.

- Function File:
**rot90***(*`A`) - Function File:
**rot90***(*`A`,`k`) Rotate array by 90 degree increments.

Return a copy of

`A`with the elements rotated counterclockwise in 90-degree increments.The second argument is optional, and specifies how many 90-degree rotations are to be applied (the default value is 1). Negative values of

`k`rotate the matrix in a clockwise direction. For example,rot90 ([1, 2; 3, 4], -1) ⇒ 3 1 4 2

rotates the given matrix clockwise by 90 degrees. The following are all equivalent statements:

rot90 ([1, 2; 3, 4], -1) rot90 ([1, 2; 3, 4], 3) rot90 ([1, 2; 3, 4], 7)

The rotation is always performed on the plane of the first two dimensions, i.e., rows and columns. To perform a rotation on any other plane, use

`rotdim`

.

- Function File:
**rotdim***(*`x`) - Function File:
**rotdim***(*`x`,`n`) - Function File:
**rotdim***(*`x`,`n`,`plane`) Return a copy of

`x`with the elements rotated counterclockwise in 90-degree increments.The second argument

`n`is optional, and specifies how many 90-degree rotations are to be applied (the default value is 1). Negative values of`n`rotate the matrix in a clockwise direction.The third argument is also optional and defines the plane of the rotation. If present,

`plane`is a two element vector containing two different valid dimensions of the matrix. When`plane`is not given the first two non-singleton dimensions are used.For example,

rotdim ([1, 2; 3, 4], -1, [1, 2]) ⇒ 3 1 4 2

rotates the given matrix clockwise by 90 degrees. The following are all equivalent statements:

rotdim ([1, 2; 3, 4], -1, [1, 2]) rotdim ([1, 2; 3, 4], 3, [1, 2]) rotdim ([1, 2; 3, 4], 7, [1, 2])

- Built-in Function:
**cat***(*`dim`,`array1`,`array2`, …,`arrayN`) Return the concatenation of N-D array objects,

`array1`,`array2`, …,`arrayN`along dimension`dim`.A = ones (2, 2); B = zeros (2, 2); cat (2, A, B) ⇒ 1 1 0 0 1 1 0 0

Alternatively, we can concatenate

`A`and`B`along the second dimension in the following way:[A, B]

`dim`can be larger than the dimensions of the N-D array objects and the result will thus have`dim`dimensions as the following example shows:cat (4, ones (2, 2), zeros (2, 2)) ⇒ ans(:,:,1,1) = 1 1 1 1 ans(:,:,1,2) = 0 0 0 0

- Built-in Function:
**horzcat***(*`array1`,`array2`, …,`arrayN`) Return the horizontal concatenation of N-D array objects,

`array1`,`array2`, …,`arrayN`along dimension 2.Arrays may also be concatenated horizontally using the syntax for creating new matrices. For example:

`hcat`= [`array1`,`array2`, … ]

- Built-in Function:
**vertcat***(*`array1`,`array2`, …,`arrayN`) Return the vertical concatenation of N-D array objects,

`array1`,`array2`, …,`arrayN`along dimension 1.Arrays may also be concatenated vertically using the syntax for creating new matrices. For example:

`vcat`= [`array1`;`array2`; … ]

- Built-in Function:
**permute***(*`A`,`perm`) Return the generalized transpose for an N-D array object

`A`.The permutation vector

`perm`must contain the elements`1:ndims (A)`

(in any order, but each element must appear only once). The`N`th dimension of`A`gets remapped to dimension

. For example:`PERM`(`N`)`x`= zeros ([2, 3, 5, 7]); size (`x`) ⇒ 2 3 5 7 size (permute (`x`, [2, 1, 3, 4])) ⇒ 3 2 5 7 size (permute (`x`, [1, 3, 4, 2])) ⇒ 2 5 7 3 ## The identity permutation size (permute (`x`, [1, 2, 3, 4])) ⇒ 2 3 5 7**See also:**ipermute.

- Built-in Function:
**ipermute***(*`A`,`iperm`) The inverse of the

`permute`

function.The expression

ipermute (permute (A, perm), perm)

returns the original array

`A`.**See also:**permute.

- Built-in Function:
**reshape***(*`A`,`m`,`n`, …) - Built-in Function:
**reshape***(*`A`, [`m``n`…]) - Built-in Function:
**reshape***(*`A`, …, [], …) - Built-in Function:
**reshape***(*`A`,`size`) Return a matrix with the specified dimensions (

`m`,`n`, …) whose elements are taken from the matrix`A`.The elements of the matrix are accessed in column-major order (like Fortran arrays are stored).

The following code demonstrates reshaping a 1x4 row vector into a 2x2 square matrix.

reshape ([1, 2, 3, 4], 2, 2) ⇒ 1 3 2 4

Note that the total number of elements in the original matrix (

`prod (size (`

) must match the total number of elements in the new matrix (`A`))`prod ([`

).`m``n`…])A single dimension of the return matrix may be left unspecified and Octave will determine its size automatically. An empty matrix ([]) is used to flag the unspecified dimension.

- Built-in Function:
**resize***(*`x`,`m`) - Built-in Function:
**resize***(*`x`,`m`,`n`, …) - Built-in Function:
**resize***(*`x`, [`m``n`…]) Resize

`x`cutting off elements as necessary.In the result, element with certain indices is equal to the corresponding element of

`x`if the indices are within the bounds of`x`; otherwise, the element is set to zero.In other words, the statement

y = resize (x, dv)

is equivalent to the following code:

y = zeros (dv, class (x)); sz = min (dv, size (x)); for i = 1:length (sz) idx{i} = 1:sz(i); endfor y(idx{:}) = x(idx{:});

but is performed more efficiently.

If only

`m`is supplied, and it is a scalar, the dimension of the result is`m`-by-`m`. If`m`,`n`, … are all scalars, then the dimensions of the result are`m`-by-`n`-by-…. If given a vector as input, then the dimensions of the result are given by the elements of that vector.An object can be resized to more dimensions than it has; in such case the missing dimensions are assumed to be 1. Resizing an object to fewer dimensions is not possible.

- Function File:
`y`=**circshift***(*`x`,`n`) Circularly shift the values of the array

`x`.`n`must be a vector of integers no longer than the number of dimensions in`x`. The values of`n`can be either positive or negative, which determines the direction in which the values or`x`are shifted. If an element of`n`is zero, then the corresponding dimension of`x`will not be shifted. For example:x = [1, 2, 3; 4, 5, 6; 7, 8, 9]; circshift (x, 1) ⇒ 7, 8, 9 1, 2, 3 4, 5, 6 circshift (x, -2) ⇒ 7, 8, 9 1, 2, 3 4, 5, 6 circshift (x, [0,1]) ⇒ 3, 1, 2 6, 4, 5 9, 7, 8

- Function File:
**shift***(*`x`,`b`) - Function File:
**shift***(*`x`,`b`,`dim`) If

`x`is a vector, perform a circular shift of length`b`of the elements of`x`.If

`x`is a matrix, do the same for each column of`x`.If the optional

`dim`argument is given, operate along this dimension.

- Function File:
`y`=**shiftdim***(*`x`,`n`) - Function File:
*[*`y`,`ns`] =**shiftdim***(*`x`) Shift the dimensions of

`x`by`n`, where`n`must be an integer scalar.When

`n`is positive, the dimensions of`x`are shifted to the left, with the leading dimensions circulated to the end. If`n`is negative, then the dimensions of`x`are shifted to the right, with`n`leading singleton dimensions added.Called with a single argument,

`shiftdim`

, removes the leading singleton dimensions, returning the number of dimensions removed in the second output argument`ns`.For example:

x = ones (1, 2, 3); size (shiftdim (x, -1)) ⇒ [1, 1, 2, 3] size (shiftdim (x, 1)) ⇒ [2, 3] [b, ns] = shiftdim (x) ⇒ b = [1, 1, 1; 1, 1, 1] ⇒ ns = 1

- Built-in Function:
*[*`s`,`i`] =**sort***(*`x`) - Built-in Function:
*[*`s`,`i`] =**sort***(*`x`,`dim`) - Built-in Function:
*[*`s`,`i`] =**sort***(*`x`,`mode`) - Built-in Function:
*[*`s`,`i`] =**sort***(*`x`,`dim`,`mode`) Return a copy of

`x`with the elements arranged in increasing order.For matrices,

`sort`

orders the elements within columnsFor example:

sort ([1, 2; 2, 3; 3, 1]) ⇒ 1 1 2 2 3 3

If the optional argument

`dim`is given, then the matrix is sorted along the dimension defined by`dim`. The optional argument`mode`

defines the order in which the values will be sorted. Valid values of`mode`

are`"ascend"`

or`"descend"`

.The

`sort`

function may also be used to produce a matrix containing the original row indices of the elements in the sorted matrix. For example:[s, i] = sort ([1, 2; 2, 3; 3, 1]) ⇒ s = 1 1 2 2 3 3 ⇒ i = 1 3 2 1 3 2

For equal elements, the indices are such that equal elements are listed in the order in which they appeared in the original list.

Sorting of complex entries is done first by magnitude (

`abs (`

) and for any ties by phase angle (`z`)`angle (z)`

). For example:sort ([1+i; 1; 1-i]) ⇒ 1 + 0i 1 - 1i 1 + 1i

NaN values are treated as being greater than any other value and are sorted to the end of the list.

The

`sort`

function may also be used to sort strings and cell arrays of strings, in which case ASCII dictionary order (uppercase ’A’ precedes lowercase ’a’) of the strings is used.The algorithm used in

`sort`

is optimized for the sorting of partially ordered lists.

- Function File:
*[*`s`,`i`] =**sortrows***(*`A`) - Function File:
*[*`s`,`i`] =**sortrows***(*`A`,`c`) Sort the rows of the matrix

`A`according to the order of the columns specified in`c`.By default (

`c`omitted, or a particular column unspecified in`c`) an ascending sort order is used. However, if elements of`c`are negative then the corresponding column is sorted in descending order. If the elements of`A`are strings then a lexicographical sort is used.Example: sort by column 2 in descending order, then 3 in ascending order

x = [ 7, 1, 4; 8, 3, 5; 9, 3, 6 ]; sortrows (x, [-2, 3]) ⇒ 8 3 5 9 3 6 7 1 4

**See also:**sort.

- Built-in Function:
**issorted***(*`a`) - Built-in Function:
**issorted***(*`a`,`mode`) - Built-in Function:
**issorted***(*`a`, "rows",`mode`) Return true if the array is sorted according to

`mode`, which may be either`"ascending"`

,`"descending"`

, or`"either"`

.By default,

`mode`is`"ascending"`

. NaNs are treated in the same manner as`sort`

.If the optional argument

`"rows"`

is supplied, check whether the array is sorted by rows as output by the function`sortrows`

(with no options).This function does not support sparse matrices.

- Built-in Function:
**nth_element***(*`x`,`n`) - Built-in Function:
**nth_element***(*`x`,`n`,`dim`) Select the n-th smallest element of a vector, using the ordering defined by

`sort`

.The result is equivalent to

`sort(`

.`x`)(`n`)`n`can also be a contiguous range, either ascending`l:u`

or descending`u:-1:l`

, in which case a range of elements is returned.If

`x`is an array,`nth_element`

operates along the dimension defined by`dim`, or the first non-singleton dimension if`dim`is not given.Programming Note: nth_element encapsulates the C++ standard library algorithms nth_element and partial_sort. On average, the complexity of the operation is O(M*log(K)), where

`M = size (`

and`x`,`dim`)`K = length (`

. This function is intended for cases where the ratio K/M is small; otherwise, it may be better to use`n`)`sort`

.

- Function File:
**tril***(*`A`) - Function File:
**tril***(*`A`,`k`) - Function File:
**tril***(*`A`,`k`,`pack`) - Function File:
**triu***(*`A`) - Function File:
**triu***(*`A`,`k`) - Function File:
**triu***(*`A`,`k`,`pack`) Return a new matrix formed by extracting the lower (

`tril`

) or upper (`triu`

) triangular part of the matrix`A`, and setting all other elements to zero.The second argument is optional, and specifies how many diagonals above or below the main diagonal should also be set to zero.

The default value of

`k`is zero, so that`triu`

and`tril`

normally include the main diagonal as part of the result.If the value of

`k`is nonzero integer, the selection of elements starts at an offset of`k`diagonals above or below the main diagonal; above for positive`k`and below for negative`k`.The absolute value of

`k`must not be greater than the number of subdiagonals or superdiagonals.For example:

tril (ones (3), -1) ⇒ 0 0 0 1 0 0 1 1 0

and

tril (ones (3), 1) ⇒ 1 1 0 1 1 1 1 1 1

If the option

`"pack"`

is given as third argument, the extracted elements are not inserted into a matrix, but rather stacked column-wise one above other.**See also:**diag.

- Built-in Function:
`v`=**vec***(*`x`) - Built-in Function:
`v`=**vec***(*`x`,`dim`) Return the vector obtained by stacking the columns of the matrix

`x`one above the other.Without

`dim`this is equivalent to

.`x`(:)If

`dim`is supplied, the dimensions of`v`are set to`dim`with all elements along the last dimension. This is equivalent to`shiftdim (`

.`x`(:), 1-`dim`)

- Function File:
**vech***(*`x`) Return the vector obtained by eliminating all superdiagonal elements of the square matrix

`x`and stacking the result one column above the other.This has uses in matrix calculus where the underlying matrix is symmetric and it would be pointless to keep values above the main diagonal.

**See also:**vec.

- Function File:
**prepad***(*`x`,`l`) - Function File:
**prepad***(*`x`,`l`,`c`) - Function File:
**prepad***(*`x`,`l`,`c`,`dim`) Prepend the scalar value

`c`to the vector`x`until it is of length`l`. If`c`is not given, a value of 0 is used.If

`length (`

, elements from the beginning of`x`) >`l``x`are removed until a vector of length`l`is obtained.If

`x`is a matrix, elements are prepended or removed from each row.If the optional argument

`dim`is given, operate along this dimension.If

`dim`is larger than the dimensions of`x`, the result will have`dim`dimensions.

- Function File:
**postpad***(*`x`,`l`) - Function File:
**postpad***(*`x`,`l`,`c`) - Function File:
**postpad***(*`x`,`l`,`c`,`dim`) Append the scalar value

`c`to the vector`x`until it is of length`l`. If`c`is not given, a value of 0 is used.If

`length (`

, elements from the end of`x`) >`l``x`are removed until a vector of length`l`is obtained.If

`x`is a matrix, elements are appended or removed from each row.If the optional argument

`dim`is given, operate along this dimension.If

`dim`is larger than the dimensions of`x`, the result will have`dim`dimensions.

- Built-in Function:
`M`=**diag***(*`v`) - Built-in Function:
`M`=**diag***(*`v`,`k`) - Built-in Function:
`M`=**diag***(*`v`,`m`,`n`) - Built-in Function:
`v`=**diag***(*`M`) - Built-in Function:
`v`=**diag***(*`M`,`k`) Return a diagonal matrix with vector

`v`on diagonal`k`.The second argument is optional. If it is positive, the vector is placed on the

`k`-th superdiagonal. If it is negative, it is placed on the`-k`-th subdiagonal. The default value of`k`is 0, and the vector is placed on the main diagonal. For example:diag ([1, 2, 3], 1) ⇒ 0 1 0 0 0 0 2 0 0 0 0 3 0 0 0 0

The 3-input form returns a diagonal matrix with vector

`v`on the main diagonal and the resulting matrix being of size`m`rows x`n`columns.Given a matrix argument, instead of a vector,

`diag`

extracts the`k`-th diagonal of the matrix.

- Function File:
**blkdiag***(*`A`,`B`,`C`, …) Build a block diagonal matrix from

`A`,`B`,`C`, …All arguments must be numeric and either two-dimensional matrices or scalars. If any argument is of type sparse, the output will also be sparse.