mustBeScalarOrEmpty

R2026b

Validate that value is scalar or empty

Syntax

mustBeScalarOrEmpty(value)

Description

mustBeScalarOrEmpty(value) throws an error if value is not a scalar or is not an empty array. This function does not return a value. mustBeScalarOrEmpty calls the isscalar and isempty functions to determine if the input is a scalar or an empty array.

Class support: All numeric classes, logical, char, string, and MATLAB^® classes that implement isscalar and isempty.

Examples

Restrict Input to Scalar or Empty

Use mustBeScalarOrEmpty to restrict the values allowed for a function input argument.

function v = buildVector(inc)
    arguments
        inc {mustBeScalarOrEmpty}
    end
    v = 1:inc:10;
end

Passing a nonscalar to the buildVector function results in an error.

v = buildVector([1 2]);

Error using buildVector (line 3)
 v = buildVector([1 2]);
                 ^^^^^
Invalid argument at position 1. Value must be scalar or empty.

Input Arguments

value — Value to validate

scalar | empty

Value to validate, specified as a scalar or an empty array. Values that are not a scalar or are not an empty array result in an error.

Example: []

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

Tips

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

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

GPU Code Generation
Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

GPU Arrays

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

The mustBeScalarOrEmpty 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™.

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

Version History

Introduced in R2020b