mustBeTextScalar

Validate that value is single piece of text

Since R2020b

Syntax

mustBeTextScalar(value)

Description

mustBeTextScalar(value) throws an error if value is not a text scalar. A text scalar is a single piece of text, but the definition varies by data type:

• For string arrays, a single piece of text is a 1-by-1 scalar, such as “text”. The empty string "" and missing strings are special cases that also count as single pieces of text.

• For character arrays, a single piece of text is a row vector, such as ‘text’. An empty 0-by-0 char array '' is a special case that also counts as a single piece of text

• For scalar cells containing a string scalar or character vector mustBeTextScalar throws an errors.

This function does not return a value.

Examples

Validate That Input Is Text Scalar

Create an array of strings named text, and then use mustBeTextScalar to validate the value. mustBeTextScalar throws an error since the variable contains multiple strings.

text = ["this" "will" "throw" "an" "error"];
mustBeTextScalar(text)

Value must be a character vector or string scalar.

Restrict Argument Values

Use mustBeTextScalar 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 textScalarInput to text values.

function MyFunction(textScalarInput)
   arguments
      textScalarInput {mustBeTextScalar}
   end
end

Call the function. MATLAB^® calls mustBeTextScalar on the value being assigned to the argument. mustBeTextScalar issues an error because the value ["foo","bar"] is not a text scalar.

MyFunction(["foo","bar"])

Error using MyFunction (line 3)
 MyFunction(["foo","bar"])
            ^^^^^^^^^^^^^
Invalid argument at position 1. Value must be a character vector or string scalar.

Input Arguments

value — Value to validate

scalar | array

Value to validate, specified as a scalar or array. If value is not a 1 x 1 string array, "" or <missing> string, row vector character array, or '' mustBeTextScalar will throw an error.

Example: mustBeTextScalar('foo')

Extended Capabilities

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

Version History

Introduced in R2020b