mustBeSorted

Validate that input is sorted

Since R2026a

collapse all in page

Syntax

mustBeSorted(A)
mustBeSorted(A,dim)
mustBeSorted(___,direction)
mustBeSorted(___,Name=Value)

Description

mustBeSorted(A) throws an error if the elements of A are not in sorted order. This function does not return a value. mustBeSorted calls the issorted function to determine if the elements in A are sorted.

  • If A is a vector, the elements of A are considered sorted if they are in ascending order.

  • If A is a matrix, the elements of A are considered sorted if each column is in ascending order.

  • If A is a multidimensional array, the elements of A are considered sorted if they are in ascending order along the first dimension whose size does not equal 1.

  • If A is a timetable, A is considered sorted if its row time vector is in ascending order.

Class support: All numeric classes, logical, char, string, cell, categorical, datetime, duration, timetable, and MATLAB® classes that implement issorted.

example

mustBeSorted(A,dim) specifies the dimension along which A must be sorted. For example, if A is a matrix, then mustBeSorted(A,2) throws an error if each row of A is not in ascending order.

example

mustBeSorted(___,direction) specifies the sorting direction in addition to any of the input argument combinations in any of the previous syntaxes. For example, mustBeSorted(A,"monotonic") throws an error if the elements of A are not in ascending or descending order.

example

mustBeSorted(___,Name=Value) specifies additional options for checking sort order using one or more name-value arguments. For example, for an input array A that contains complex values, mustBeSorted(A,ComparisonMethod="abs") throws an error if the elements of A are not sorted by their complex magnitude.

example

Examples

collapse all

Validate that the elements in a vector are sorted. By default, mustBeSorted considers a vector to be sorted if its elements are in ascending order. Therefore, mustBeSorted throws an error for the following vector.

A = [5 3 3 1];
mustBeSorted(A)
Value must be sorted.

To check for descending order, specify the sorting direction as "descend". In this case, mustBeSorted does not throw an error for A.

mustBeSorted(A,"descend")

Use mustBeSorted within a properties block of a class definition to restrict property values. For example, ensure that the value assigned to a property is a string array sorted in ascending order along each row (sorted from left to right across the second dimension).

classdef MyClass
    properties
        PropLabel string {mustBeSorted(PropLabel,2)}
    end
end

Create an object and assign a value to its property. To validate the property value, MATLAB calls mustBeSorted and throws an error because the value assigned is not sorted in ascending order along the rows.

obj = MyClass;
A = ["duck","dog"; "puma","bird"];
obj.PropLabel = A;
Error setting property 'PropLabel' of class 'MyClass'. Value must be sorted.

If you specify the PropLabel property as a string array that is sorted in ascending order along the rows, mustBeSorted does not throw an error.

A = ["dog","duck"; "bird","puma"];
obj.PropLabel = A;

Use mustBeSorted within an arguments block of a function to restrict input argument values. For example, ensure that the value passed to a function is a numeric array that is sorted in ascending order by magnitude.

function theta = angleOfSortedDistance(r)
    arguments
        r {mustBeSorted(r,ComparisonMethod="abs")}
    end
    theta = angle(r);
end

Create a complex vector whose elements are sorted in ascending order by their real values.

r = [-3 + 4i, -1 + i, 2i, 2 - 2i];

Call the angleOfSortedDistance function with this complex vector as input. To validate the input value, MATLAB calls mustBeSorted and throws an error because r is not sorted by the magnitude of its elements.

theta = angleOfSortedDistance(r)
Error using angleOfSortedDistance (line 3)
 theta = angleOfSortedDistance(r)
                               ^
Invalid argument at position 1. Value must be sorted.

If you call angleOfSortedDistance with a vector sorted by magnitude, mustBeSorted does not throw an error.

r = [-1 + i, 2i, 2 - 2i, -3 + 4i];
theta = angleOfSortedDistance(r)
theta =

    2.3562    1.5708   -0.7854    2.2143

Input Arguments

collapse all

Values to validate, specified as a vector, matrix, or multidimensional array.

  • If A contains missing values, such as NaN, NaT, <undefined>, and missing, then by default, mustBeSorted requires that these values appear at the end to validate that A is sorted.

  • If A is complex, then by default, mustBeSorted validates sort order by the magnitude of the elements. If A contains consecutive elements with equal magnitude, then mustBeSorted also checks the phase angle in the interval (–π, π] to break ties.

  • If A is a cell array of character vectors or a string array, then mustBeSorted validates sort order using the code order for the UTF-16 character encoding scheme. The sort is case sensitive. For more information on sorted character and string arrays, see Sort Order for Character and String Arrays.

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

Dimension to operate along, specified as a positive integer scalar. If you do not specify dim, then the default is the first array dimension whose size does not equal 1.

Consider a matrix A. mustBeSorted(A,1) validates that the data in each column of A is sorted.

mustBeSorted(A,2) validates that the data in each row of A is sorted.

dim is not supported for timetable input.

Data Types: double | single | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

Sorting direction, specified as one of these values:

  • "ascend" — Validate that the data is in ascending order. Data can contain consecutive repeated elements.

  • "descend" — Validate that the data is in descending order. Data can contain consecutive repeated elements.

  • "monotonic" — Validate that the data is in either ascending or descending order. Data can contain consecutive repeated elements.

  • "strictascend" — Validate that the data is in strictly ascending order. Data cannot contain duplicate or missing elements.

  • "strictdescend" — Validate that the data is in strictly descending order. Data cannot contain duplicate or missing elements.

  • "strictmonotonic" — Validate that the data is in strictly ascending or strictly descending order. Data cannot contain duplicate or missing elements.

direction is not supported for timetable input.

Name-Value Arguments

collapse all

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.

Example: mustBeSorted(A,MissingPlacement="last")

Placement of missing values (NaN, NaT, <undefined>, and missing), specified as one of these values:

  • "auto" — Missing elements must appear last for ascending order and first for descending order for A to satisfy the sorting criteria.

  • "first" — Missing elements must appear first for A to satisfy the sorting criteria.

  • "last" — Missing elements must appear last for A to satisfy the sorting criteria.

This name-value argument is not supported for timetable input.

Element comparison method for numeric input, specified as one of these values:

  • "auto" — Validate that A is sorted by real(A) when A is real, and by abs(A) when A is complex.

  • "real" — Validate that A is sorted by real(A) when A is real or complex. If A contains elements with consecutive equal real parts, then mustBeSorted checks imag(A) to break ties.

  • "abs" — Validate that A is sorted by abs(A) when A is real or complex. If A contains elements with consecutive equal magnitude, then mustBeSorted checks angle(A) in the interval (–π, π] to break ties.

Tips

  • mustBeSorted is designed to be used for property and function argument validation.

Extended Capabilities

expand all

Version History

Introduced in R2026a

expand all

See Also

Functions

Topics