mustBeTextScalar

Validate that value is single piece of text

collapse all in page

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 error.

This function does not return a value.

example

Examples

collapse all

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.

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

collapse all

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

expand all

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

Version History

Introduced in R2020b

See Also

| |

Topics