mustBeText

R2026b

Validate that value is string array, character vector, or cell array of character vectors

Syntax

mustBeText(value)

Description

mustBeText(value) throws an error if value is not a string array, character vector, or cell array of character vectors. An empty 0x0 char array '', empty string "", and missing strings are special cases that also counts as text. This function does not return a value.

Examples

Validate That Input Is Text

Create an array of numbers notText, and then use mustBeText to validate the value. mustBeText throws an error since the array does not contain text.

notText = [1 2 3];
mustBeText(notText)

Value must be a character vector, string array, or cell array of character vectors.

Restrict Argument Values

Use mustBeText 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 restricts the value of the argument textInput to text values.

function MyFunction(textInput)
   arguments
      textInput {mustBeText}
   end
end

Call the function with a numeric input argument. MATLAB^® calls mustBeText on the value being assigned to the argument. mustBeText issues an error because the value 2 is not text.

MyFunction(2)

Error using MyFunction (line 3)
 MyFunction(2)
            ^
Invalid argument at position 1. Value must be a character vector, string array, or cell array of character vectors.

Input Arguments

value — Value to validate

scalar | array

Value to validate, specified as a scalar or array. If value, is not a string scalar or array, character array, or cell array of character vectors mustBeText will throw an error.

Example: mustBeText('foo')

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™. (since R2026b)

The mustBeText 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™. (since R2026b)

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

Version History

Introduced in R2020b

R2026b: Accelerate code by running on GPU

You can accelerate your code by running the mustBeText function on a GPU. GPU computing requires Parallel Computing Toolbox™.

R2026b: Scale up your code using distributed arrays

You can scale up your code by running the mustBeText function with distributed arrays, enabling you to leverage the combined memory of a compute cluster. Using distributed arrays requires Parallel Computing Toolbox.