issortedrows

Determine if matrix or table rows are sorted

Syntax

TF = issortedrows(A)

TF = issortedrows(A,column)

TF = issortedrows(___,direction)

TF = issortedrows(___,Name,Value)

TF = issortedrows(tblA)

TF = issortedrows(tblA,'RowNames')

TF = issortedrows(tblA,rowDimName)

TF = issortedrows(tblA,vars)

TF = issortedrows(___,direction)

TF = issortedrows(___,Name,Value)

Description

TF = issortedrows(A) returns logical 1 (true) when the elements of the first column of A are in sorted order and logical 0 (false) otherwise. By default, issortedrows looks for ascending sorted order. When the first column has consecutive repeated elements, issortedrows determines whether the next column is in ascending order, and repeats this behavior for succeeding equal values.

TF = issortedrows(A,column) returns 1 when A is sorted based on the columns specified in the vector column. For example, issortedrows(A,[4 6]) first checks if the fourth column of A is in ascending order, then checks if the sixth column is in ascending order to break ties.

TF = issortedrows(___,direction) returns 1 when the first column of A is in the order specified by direction for any of the previous syntaxes. For example, issortedrows(A,'monotonic') checks if the first column of A is in ascending or descending order. direction can also be a cell array of character vectors representing multiple directions for each column being checked. For example, issortedrows(A,[2 3],{'ascend' 'descend'}) checks if the second column of A is in ascending order, then checks if the third column is in descending order to break ties.

TF = issortedrows(___,Name,Value) specifies additional parameters for checking sort order. For example, issortedrows(A,'ComparisonMethod','abs') checks if the elements in the first column of A are sorted by magnitude.

TF = issortedrows(tblA) checks if the rows of a table are in ascending order based on the elements in the first variable. If elements in the first variable are repeated, then issortedrows checks the elements in the second variable, and so on.

If tblA is a timetable, then issortedrows checks if the rows of tblA are in ascending order based on its row times. Row times of a timetable label the rows along the first dimension of the timetable.

TF = issortedrows(tblA,'RowNames') checks if the rows of a table are in ascending order based on its row names. Row names of a table label the rows along the first dimension of the table.

This syntax is not supported when tblA is a timetable.

TF = issortedrows(tblA,rowDimName) checks if the rows of a table are sorted by row labels rowDimName along the first dimension.

• If tblA is a table, then the labels are row names.

• If tblA is a timetable, then the labels are row times.

TF = issortedrows(tblA,vars) checks if the rows of a table are in ascending order based on the elements in variables vars. For example, if Age and Weight are variables of tblA, then issortedrows(tblA,{'Age','Weight'}) checks if the rows are in ascending order by age, then by weight to break ties.

• If tblA is a table with row names, then vars can include the row names.

• If tblA is a timetable, then vars can include the row times.

TF = issortedrows(___,direction) checks if a table is sorted in the order specified by direction for any of the previous table syntaxes. direction can be a single sort order such as 'descend' or 'monotonic', which is applied to each specified variable, row name, or row time. direction can also be a cell array whose elements contain different sort orders for each specified variable, row name, or row time that issortedrows operates on.

TF = issortedrows(___,Name,Value) specifies additional parameters for sorting tables. For example, issortedrows(tblA,'Var1','MissingPlacement','first') checks that missing elements in Var1, such as NaN or NaT, are placed at the beginning of the table.

Examples

Matrix Rows

Create a matrix and determine if its rows are in ascending order based on the values in the first column. Since the first column has a repeated element, sortrows looks to the second column to determine whether the matrix rows are sorted.

A = [1 2 9; 1 5 8; 4 0 7]

A = 3×3

     1     2     9
     1     5     8
     4     0     7

TF = issortedrows(A)

TF = logical
   1

Determine if the rows of A are in ascending order based on the values in the third column.

TF = issortedrows(A,3)

TF = logical
   0

Determine if the rows of A are in descending order based on the values in the third column.

TF = issortedrows(A,3,'descend')

TF = logical
   1

Complex Matrix

Create a matrix containing complex numbers, and determine if its rows are in ascending order based on the real parts of the elements in the first column. Since the elements in the first column have equal real parts, issortedrows then checks the imaginary parts to break the tie.

A = [1+i 2i; 1+2i 3+4i]

A = 2×2 complex

   1.0000 + 1.0000i   0.0000 + 2.0000i
   1.0000 + 2.0000i   3.0000 + 4.0000i

TF = issortedrows(A,'ComparisonMethod','real')

TF = logical
   1

Table Rows

For a table that describes patient information for five people, determine how the rows of the table are sorted.

Create a table with four variables, and determine if the rows of the table are in ascending order based on age. Since the age variable contains a repeated element, issortedrows then checks the next column (Height) to break the tie.

LastName = {'Sweet';'Jacobson';'Wang';'Joiner';'Berger'};
Age = [38;38;40;43;49];
Height = [69;71;64;67;64];
Weight = [176;163;131;133;119];
BloodPressure = [124 93; 109 77; 125 83; 117 75; 122 80];

tblA = table(Age,Height,Weight,BloodPressure,'RowNames',LastName)

tblA=5×4 table
                Age    Height    Weight    BloodPressure
                ___    ______    ______    _____________

    Sweet       38       69       176       124     93  
    Jacobson    38       71       163       109     77  
    Wang        40       64       131       125     83  
    Joiner      43       67       133       117     75  
    Berger      49       64       119       122     80  

TF = issortedrows(tblA)

TF = logical
   1

Check if the table rows are sorted by last name, which are the row names for tblA.

TF = issortedrows(tblA,'RowNames')

TF = logical
   0

Check if the table rows are in ascending order by age, then in descending order by weight.

TF = issortedrows(tblA,{'Age','Weight'},{'ascend','descend'})

TF = logical
   1

Timetable with Missing Times

Create a timetable, and check that the rows of the timetable are in ascending order based on the row times. Also check that missing elements are placed last.

Time = [seconds(1:3) NaN NaN]';
TT = timetable(Time,[98;97.5;97.9;98.1;99.9],[120;111;119;117;112],...
               'VariableNames',{'Temperature','Distance'})

TT=5×2 timetable
     Time      Temperature    Distance
    _______    ___________    ________

    1 sec           98          120   
    2 sec         97.5          111   
    3 sec         97.9          119   
    NaN sec       98.1          117   
    NaN sec       99.9          112   

TF = issortedrows(TT,'Time','MissingPlacement','last')

TF = logical
   1

Input Arguments

A — Input array

column vector | matrix

Input array, specified as a column vector or matrix.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration
Complex Number Support: Yes

column — Column sorting vector

nonzero integer scalar | vector of nonzero integers

Column sorting vector, specified as a nonzero integer scalar or a vector of nonzero integers. Each specified integer value indicates a column to check for sort order. Negative integers indicate that the sort order is descending.

direction — Sorting direction

'ascend' (default) | 'descend' | 'monotonic' | 'strictascend' | 'strictdescend' | 'strictmonotonic'

Sorting direction, specified as one of the following:

• 'ascend' — Checks if data is in ascending order. Data can contain consecutive repeated elements.

• 'descend' — Checks if data is in descending order. Data can contain consecutive repeated elements.

• 'monotonic' — Checks if data is in descending or ascending order. Data can contain consecutive repeated elements.

• 'strictascend' — Checks if data is in strictly ascending order. Data cannot contain duplicate or missing elements.

• 'strictdescend' — Checks if data is in strictly descending order. Data cannot contain duplicate or missing elements.

• 'strictmonotonic' — Checks if data is in strictly descending or strictly ascending order. Data cannot contain duplicate or missing elements.

direction can also be a cell array containing a list of these character vectors, where each element in the list corresponds to a column of A. For example, issortedrows(A,[2 4],{'ascend' 'descend'}) first checks if the rows of A are in ascending order based on the second column. Then, to break ties, issortedrows checks if the rows are in descending order based on the fourth column.

If column is specified, then the number of elements in the cell array must match the length of column. When column is not specified, the cell array must contain an element for every column of A, or a single element that is applied to all columns.

Data Types: char | cell

tblA — Input table

table | timetable

Input table, specified as a table or a timetable. Each variable in tblA must be a valid input to sort or sortrows.

Data Types: table | timetable

rowDimName — Name of first dimension of input table or timetable

string scalar | character vector

Name of the first dimension of the input table or timetable, specified as a string scalar or character vector.

• If tblA is a table with row names, then rowDimName is the name of the first dimension of the table. By default, the name of the first dimension is 'Row'. Dimension names are a property of tables. You can access the dimension names of tblA using tblA.Properties.DimensionNames.

• If tblA is a timetable, then rowDimName is the name of the vector of row times. You can specify its name when you create a timetable, such as Time or Date. You can also access the dimension names using tblA.Properties.DimensionNames.

Example: If a table T has row names, and you changed the name of the first dimension using T.Properties.DimensionName{1} = "Name", then issortedrows(T,"Name") checks if the table is sorted by row names.

Example: If a timetable TT has a time vector named Date, then issortedrows(TT,"Date") checks if the timetable is sorted by the dates and times that Date contains.

Data Types: string | char

vars — Sorting variables

scalar integer | vector of integers | variable name | string array of variable names | cell array of variable names | pattern scalar | logical vector

Sorting variables, specified as a scalar integer, a vector of integers, a variable name, a string array of variable names, a cell array of variable names, a pattern scalar, or a logical vector. vars indicates the table variables to sort by.

If you do not specify the direction argument, the sign of the elements in vars determines the sorting direction of the variables. If an element is a positive integer, then issortedrows checks whether the rows in the corresponding variable in tblA are in ascending order. If an element is a negative integer, then issortedrows checks whether the rows in the corresponding variable in tblA are in descending order. Otherwise, if you specify the direction argument, issortedrows ignores the sign of vars and checks whether the specified variables are sorted according to direction.

Example: issortedrows(tblA,["Height","Weight"]) checks if the rows of tblA are in ascending order, first by the variable Height, then by the variable Weight to break ties.

Example: issortedrows(tblA,"X" + wildcardPattern) checks if the rows of tblA are in ascending order based on the table variables whose names begin with the letter "X", using a wildcard pattern to match the remaining letters in their names.

Example: issortedrows(tblA,[1 4]) first checks if the table rows are in ascending order based on the first variable, then breaks ties by checking if the rows are in ascending order based on the fourth variable.

Example: issortedrows(TT,["Time","X"]) checks if the row times of a timetable are in ascending order, then breaks ties by checking if the rows are in ascending order based on the table variable X.

Data Types: double | single | string | char | cell | pattern | logical

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.

Example: issortedrows(A,'MissingPlacement','last')

MissingPlacement — Placement of missing values

'auto' (default) | 'first' | 'last'

Placement of missing values (NaN, NaT, <undefined>, and missing) specified as the comma-separated pair consisting of 'MissingPlacement' and one of the following:

• 'auto' — Missing elements are required to be placed last for ascending order and first for descending order to return 1.

• 'first' — Missing elements are required to be placed first to return 1.

• 'last' — Missing elements are required to be placed last to return 1.

ComparisonMethod — Element comparison method

'auto' (default) | 'real' | 'abs'

Element comparison method for numeric input, specified as the comma-separated pair consisting of 'ComparisonMethod' and one of the following:

• 'auto' — Check if the rows of A are sorted by real(A) when A is real, and check if the rows of A are sorted by abs(A) when A is complex.

• 'real' — Check if the rows of A are sorted by real(A) when A is real or complex. If a column has elements with consecutive equal real parts, then check imag(A) to break ties.

• 'abs' — Check if the rows of A are sorted by abs(A) when A is real or complex. If a column has elements with consecutive equal magnitude, then check angle(A) in the interval (-π,π] to break ties.

Extended Capabilities

Tall Arrays

Calculate with arrays that have more rows than fit in memory.

The issortedrows function fully supports tall arrays. For more information, see Tall Arrays.

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• If A is complex with all zero imaginary parts, then MATLAB^® might convert A to real(A) before calling issortedrows(A). In this case, MATLAB checks that the rows of A are sorted by real(A), but the generated code checks that the rows of A are sorted by abs(A). To make the generated code match MATLAB, use issortedrows(real(A)) or issortedrows(A,'ComparisonMethod','real'). See Code Generation for Complex Data with Zero-Valued Imaginary Parts (MATLAB Coder).

• If tblA is a table or timetable, then the input argument vars must be constant.

• If tblA has any variables that have multiple columns, then those variables must have fixed widths.

• The vars input argument does not support pattern expressions.

Thread-Based Environment

Run code in the background using MATLAB® backgroundPool or accelerate code with Parallel Computing Toolbox™ ThreadPool.

This function fully supports thread-based environments. For more information, see Run MATLAB Functions in Thread-Based Environment.

Distributed Arrays

Partition large arrays across the combined memory of your cluster using Parallel Computing Toolbox™.

This function fully supports distributed arrays. For more information, see Run MATLAB Functions with Distributed Arrays (Parallel Computing Toolbox).

Version History

Introduced in R2017a