mustBeUnderlyingType

Validate that value has specified underlying type

Syntax

mustBeUnderlyingType(value,typenames)

Description

mustBeUnderlyingType(value,typenames) throws an error if value does not have any of the underlying data types specified by typenames. 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 one of these underlying data types: 'double'.

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

You can specify more than one data type to check against. (since R2024a) Define a second distributed array of type double.

y = distributed(double(1:10));

mustBeUnderlyingType does not throw an error for x or y when both double and single are specified.

mustBeUnderlyingType(x,["double","single"])
mustBeUnderlyingType(y,["double","single"])

Restrict Function Argument Values

Use mustBeUnderlyingType to restrict the input argument values that are accepted by a function. Include an arguments block 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 mbSingle(input)
    arguments
        input {mustBeUnderlyingType(input,"single")}
    end

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

Create a distributed vector (requires Parallel Computing Toolbox) that has underlying data of type single.

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

Because the input passes the argument validation, the mbSingle function prints information about the class and underlying type.

mbSingle(x)

Input is class distributed with underlying type single.

Container Classes

mustBeUnderlyingType identifies a variable by its container class instead of its contents when the data type of the contents does not change the behavior of the container. Cell arrays and tables are examples of this type of container.

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

function mbDouble(input)
    arguments
        input {mustBeUnderlyingType(input,"double")}
    end

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

Call the function with a cell array that contains only double values. Because mustBeUnderlyingType identifies the data type as a cell array, the validation fails even though the contents are double.

x = {1,2,3};
mbDouble(x)

Error using mbDouble (line 3)
 mbDouble(x)
          ^
Invalid argument at position 1. Value must have one of these underlying types: double.

This function, which requires that the input be a cell array, accepts x without error.

function mbCell(input)
    arguments
        input {mustBeUnderlyingType(input,"cell")}
    end
    
    disp("Input is class " + class(input) + ...
        " with underlying type " + underlyingType(input) + ".")
end

mbCell(x)

Input is class cell with underlying type cell.

For more examples, see underlyingType.

Input Arguments

value — Value to validate

scalar | array | object

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

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

typenames — Name of one or more data types to test

string array | character vector | cell array of character vectors

Name of one or more data types to test, specified as a string array, character vector, or cell array of character vectors.

Example: mustBeUnderlyingType(X,["double","single"]) throws an error if X does not have underlying type double or single.

Tips

• mustBeUnderlyingType 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 Arrays

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

The mustBeUnderlyingType 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 R2020b

R2024a: mustBeUnderlyingType now accepts more than one data type for comparison

The typenames input argument now accepts multiple data types for comparison, specified as a string array or a cell array of character vectors.