Argument Validation Functions - MATLAB & Simulink (original) (raw)
MATLAB defines functions for use in argument validation. These functions support common use patterns for validation and provide descriptive error messages. The following tables categorize the MATLAB® validation functions and describe their use.
Numeric Value Attributes
| Name | Meaning | Functions Called on Inputs |
|---|---|---|
| mustBePositive(value) | value > 0 | gt, isreal, isnumeric, islogical |
| mustBeNonpositive(value) | value <= 0 | ge, isreal, isnumeric, islogical |
| mustBeNonnegative(value) | value >= 0 | ge, isreal, isnumeric, islogical |
| mustBeNegative(value) | value < 0 | lt, isreal, isnumeric, islogical |
| mustBeFinite(value) | value has no NaN and no Inf elements. | isfinite |
| mustBeNonNan(value) | value has no NaN elements. | isnan |
| mustBeNonzero(value) | value ~= 0 | eq, isnumeric, islogical |
| mustBeNonsparse(value) | value is not sparse. | issparse |
| mustBeSparse(value) | value is sparse. | issparse |
| mustBeReal(value) | value has no imaginary part. | isreal |
| mustBeInteger(value) | value == floor(value) | isreal, isfinite, floor, isnumeric, islogical |
| mustBeNonmissing(value) | value cannot contain missing values. | ismissing |
Comparison with Other Values
| Name | Meaning | Functions Called on Inputs |
|---|---|---|
| mustBeGreaterThan(value,c) | value > c | gt, isreal, isnumeric,islogical |
| mustBeLessThan(value,c) | value < c | lt, isreal, isnumeric, islogical |
| mustBeGreaterThanOrEqual(value,c) | value >= c | ge, isreal, isnumeric, islogical |
| mustBeLessThanOrEqual(value,c) | value <= c | le, isreal, isnumeric, islogical |
Data Types
Size
Membership and Range
Text
Define Validation Functions
Validation functions are MATLAB functions that check requirements on values entering functions or properties. Validation functions determine when to throw errors and what error messages to display.
Functions used for validation have these design elements:
- Validation functions do not return outputs or modify program state. The only purpose is to check the validity of the input value.
- Validation functions must accept the value being validated as an argument. If the function accepts more than one argument, the first input is the value to be validated.
- Validation functions rely only on the inputs. No other values are available to the function.
- Validation functions throw an error if the validation fails.
Creating your own validation function is useful when you want to provide specific validation that is not available using the MATLAB validation functions. You can create a validation function as a local function within the function file or place it on the MATLAB path. To avoid a confluence of error messages, do not use function argument validation within user-defined validation functions.
For example, the mustBeRealUpperTriangular function restricts the input to real-valued, upper triangular matrices. The validation function uses the istriu and isreal functions.
function mustBeRealUpperTriangular(a) if ~(istriu(a) && isreal(a)) eidType = 'mustBeRealUpperTriangular:notRealUpperTriangular'; msgType = 'Input must be a real-valued, upper triangular matrix.'; error(eidType,msgType) end end
If the argument is not of the correct type, the function throws an error.
a = [1 2 3+2i; 0 2 3; 0 0 1]; mustBeRealUpperTriangular(a)
Input must be a real-valued, upper triangular matrix.