str2num

Convert character array or string to numeric array

Syntax

X = str2num(chr)

[X,tf] = str2num(chr)

Description

X = str2num(chr) converts a character array or string scalar to a numeric matrix. The input can include spaces, commas, and semicolons to indicate separate elements. If str2num cannot parse the input as numeric values, then it returns an empty matrix.

The str2num function does not convert cell arrays or nonscalar string arrays, and is sensitive to spacing around + and - operators.

Note

Security Considerations: str2num is implemented using the eval function, which evaluates the input argument. When calling str2num with untrusted user input, validate the input to avoid unexpected code execution. Examples of untrusted user input are data coming from a user you might not know or from a source you have no control over. If you need to address this concern, consider these approaches:

• Validate inputs to str2num. First, search for allowed operations, such as the use of (), /, *, +, -, and ., and the letters e and i. Then, if you find other operations, disallow execution.

• Replace str2num with a function such as str2double.

Unintended Side Effects: In addition, there can be other unintended side effects when the input includes a function name. To avoid these issues, use str2double.

[X,tf] = str2num(chr) additionally returns a second output argument that is 1 (true) if str2num successfully converts chr. Otherwise, str2num returns 0 (false).

Examples

Convert to Numeric Matrix

Convert character vectors that represent numbers.

X = str2num('100')

X = 100

X = str2num('100 200 300 400')

X = 1×4

   100   200   300   400

str2num interprets exponential notation.

X = str2num('12e-3 5.9e-3 -8.1e-3 2.56e-3; 5 11.2 17.9 33')

X = 2×4

    0.0120    0.0059   -0.0081    0.0026
    5.0000   11.2000   17.9000   33.0000

Convert to Integer

Convert a character vector to an unsigned 16-bit integer using str2num and uint16.

X = str2num('256');
X = uint16(X)

X = uint16
    256

Convert to Logical

Convert a character vector containing true and false to a logical array.

X = str2num('false true true false')

X = 1x4 logical array

   0   1   1   0

Check Conversion Status

Return the status of a conversion that fails. tf is 0, and X is an empty matrix.

[X,tf] = str2num('12e-3 m/s, 5.9e-3 m/s')

X =

     []

tf = logical
   0

If you remove the extra text (m/s), then conversion succeeds.

[X,tf] = str2num('12e-3 5.9e-3')

X = 1×2

    0.0120    0.0059

tf = logical
   1

Input Arguments

chr — Representation of numeric matrix

character array | string scalar

Representation of a numeric matrix, specified as a character array or string scalar.

Text that represents a numeric matrix can contain spaces, commas, or semicolons, such as '5', '10,11,12', or '5,10;15,20'. In addition to numeric values and delimiters, input text also can include any of the following items:

• A decimal point

• Leading + or - signs

• The letter e or d preceding a power of 10 scale factor

• The letter i or j indicating a complex or imaginary number

• true or false indicating logical values

Space characters, or the lack of them, can be significant. For instance, str2num('1+2i') and str2num('1 + 2i') both return the complex number 1.0000 + 2.0000i, while str2num('1 +2i') returns the 1-by-2 vector [1.0000 + 0.0000i 0.0000 + 2.0000i]. To avoid this problem, use the str2double function.

str2num converts character arrays and string scalars only. To convert nonscalar string arrays or cell arrays to numeric arrays, use the str2double function.

Output Arguments

X — Output array

numeric matrix

Output array, returned as a numeric matrix.

tf — True or false

1 | 0

True or false result, returned as a 1 or 0 of data type logical.