mustBeBetween

Validate that all elements are within specified range

Since R2025a

Syntax

mustBeBetween(A,lower,upper)

mustBeBetween(A,lower,upper,intervalType)

mustBeBetween(___,DataVariables=vars)

Description

mustBeBetween(A,lower,upper) throws an error if any element in A is outside the range defined by lower and upper. A value is within the range if it is greater than or equal to lower, and less than or equal to upper. This function does not return a value.

mustBeBetween calls the allbetween function to determine if all elements in A are within the specified range.

Class support: All numeric classes, logical, char, string, categorical, datetime, duration, and MATLAB^® classes that overload allbetween or isbetween.

mustBeBetween(A,lower,upper,intervalType) specifies the type of interval. For example, mustBeBetween(A,lower,upper,"open") validates that all elements in A are within the open interval (lower, upper).

mustBeBetween(___,DataVariables=vars) specifies the table or timetable variables to operate on in addition to any of the input argument combinations in previous syntaxes. For example, for table A, mustBeBetween(A,lower,upper,DataVariables="Var1") validates that elements in table variable Var1 are within the specified range.

Examples

Validate That Elements Are Within Open and Closed Intervals

Validate that all elements in a vector are within the open interval (0, 5). mustBeBetween throws an error because 5 is equal to the upper bound, which is excluded from the range.

mustBeBetween([3 4 5],0,5,"open")

Value must be within the range specified by 0 and 5.

Specify the range as the closed interval [0, 5]. mustBeBetween does not throw an error.

mustBeBetween([3 4 5],0,5,"closed")

Restrict Function Argument Values

You can restrict the range of values that a function accepts as input by using the mustBeBetween function in its arguments block. For example, the mustBeBetween function definition restricts the input argument to values within the range [0, 5].

function b = checkBetween(x)
    arguments
        x {mustBeBetween(x,0,5)}
    end
    b = x - 5;
end

Call the checkBetween function with a value outside the allowed range. MATLAB calls mustBeBetween and throws an error because x is not within the allowed range.

x = 10;
b = checkBetween(x);

Error using checkBetween (line 3)
 b = checkBetween(x);
               ^
Invalid argument at position 1. Value must be within the range specified by 0 and 5.

If you call the checkBetween function with a value within the allowed range, mustBeBetween does not throw an error.

x = 3;
b = checkBetween(x);

Input Arguments

A — Values to validate

array | table | timetable

Values to validate, specified as an array of one of these types or as a table or timetable containing variables of these types:

• All numeric classes, logical, char, string, categorical, datetime, or duration

• All MATLAB classes that overload allbetween or isbetween

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | categorical | datetime | duration | table | timetable

lower — Lower bound of range

array | one-row table

Lower bound of the range, specified as an array or one-row table. The lower and upper bounds must either be the same size or have sizes that are compatible. The bounds must also have the same data type as A or a type that can be compared with A.

• To use the same lower bound for all elements of A, specify lower as a scalar.

• To use different lower bounds for each column or row in A, specify lower as a row or column vector, respectively.

• To use a different lower bound for each data element, specify lower as an array of the same size as A.

If the values to validate are in a table or timetable, when the table variables to operate on have different data types, specify the lower bound as a one-row table. The variable names of the one-row table must be the same as the names of the table variables to operate on.

upper — Upper bound of range

array | one-row table

Upper bound of the range, specified as an array or one-row table. The lower and upper bounds must either be the same size or have sizes that are compatible. The bounds must also have the same data type as A or a type that can be compared with A.

• To use the same upper bound for all elements of A, specify upper as a scalar.

• To use different upper bounds for each column or row in A, specify upper as a row or column vector, respectively.

• To use a different upper bound for each data element, specify upper as an array of the same size as A.

If the values to validate are in a table or timetable, when the table variables to operate on have different data types, specify the upper bound as a one-row table. The variable names of the one-row table must be the same as the names of the table variables to operate on.

intervalType — Type of interval

"closed" (default) | "open" | "openleft" | "openright" | "closedright" | "closedleft"

Type of interval that defines the range of allowed values, specified as one of the values in this table.

Type of Interval	Diagram	Description
"closed"		Include lower and upper.
"open"		Exclude lower and upper.
"openleft" or "closedright"		Exclude lower and include upper. "openleft" and "closedright" have the same behavior.
"openright" or "closedleft"		Include lower and exclude upper. "openright" and "closedleft" have the same behavior.

vars — Table or timetable variables to operate on

table variable name | scalar | vector | cell array | pattern | function handle | table vartype subscript

Table or timetable variables to operate on, specified as one of the values in this table. mustBeBetween operates only on elements in the specified variables in A.

If you do not specify vars, mustBeBetween operates on all variables in A.

Indexing Scheme	Values to Specify	Examples
Variable name	A string scalar or character vector A string array or cell array of character vectors A pattern object	"A" or 'A' — A variable named A ["A" "B"] or {'A','B'} — Two variables named A and B "Var"+digitsPattern(1) — Variables named "Var" followed by a single digit
Variable index	An index number that refers to the location of a variable in the table A vector of numbers A logical vector. Typically, this vector is the same length as the number of variables, but you can omit trailing 0 (false) values.	3 — The third variable from the table [2 3] — The second and third variables from the table [false false true] — The third variable
Function handle	A function handle that takes a table variable as input and returns a logical scalar	@isnumeric — All the variables containing numeric values
Variable type	A vartype subscript that selects variables of a specified type	vartype("numeric") — All the variables containing numeric values

Example: mustBeBetween(A,lower,upper,DataVariables=["Var1" "Var2" "Var4"]) validates that the elements in the Var1, Var2, and Var4 variables in table A are within the specified range.

Tips

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

Extended Capabilities

GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

The mustBeBetween function fully supports GPU arrays. To run the function on a GPU, specify the input data as a gpuArray (Parallel Computing Toolbox). For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

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 R2025a