mustBeUnderlyingType

Validate that value has specified underlying type

Since R2020b

Syntax

mustBeUnderlyingType(value,typename)

Description

mustBeUnderlyingType(value,typename) throws an error if value does not have underlying data type typename. This function does not return a value.

mustBeUnderlyingType calls the following function to determine if the input has the specified underlying type:

• underlyingType

Class support: All MATLAB^® classes

Examples

Validate That Argument Has Specified Underlying Type

Use mustBeUnderlyingType to validate that the input has underlying type double.

Create a distributed array (requires Parallel Computing Toolbox™) and then validate that the underlying data type is double.

x = distributed(single(1:10));
mustBeUnderlyingType(x,"double")

Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 6).

Value must have underlying type 'double'.

mustBeUnderlyingType throws an error because the underlying type of the distributed array is single.

Restrict Function Argument Values

Use mustBeUnderlyingType to restrict the input argument values that are accepted by a function. You can accomplish this by adding an arguments block to the function that validates the input arguments.

This function declares one input argument. In the arguments block, the input is required to have an underlying data type of single.

function y = mbSingle(input)
    arguments
        input {mustBeUnderlyingType(input,"single")}
    end

    disp("Input is class " + class(input) + ...
        " with underlying type " + underlyingType(input) + ".")
end

Call the function with a distributed vector (requires Parallel Computing Toolbox) that has underlying data of type single. Since the input passes the argument validation, the mbSingle function prints information about the class and underlying type.

x = distributed(single(1:10));
mbSingle(x)

Starting parallel pool (parpool) using the 'local' profile ...
Connected to the parallel pool (number of workers: 6).
Input is class distributed with underlying type single.

Input Arguments

value — Value to validate

scalar | array | object

Value to validate, specified as a scalar, array, or object.

Example: mustBeUnderlyingType(magic(4),"single")

typename — Name of data type to test

character vector | string scalar

Name of data type to test, specified as a character vector or string scalar.

Example: mustBeUnderlyingType(X,"double") throws an error is X does not have underlying type double.

Data Types: char | string

Tips

• mustBeUnderlyingType 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™.

This function fully supports GPU arrays. 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 R2020b