Convert Text to Numeric Values

This example shows how to convert text to the numeric values that it represents. Typically, you need to perform such conversions when you have text that represents numbers to be plotted or used in calculations. For example, the text might come from a text file or spreadsheet. If you did not already convert it to numeric values when importing it into MATLAB®, you can use the functions shown in this example.

You can convert string arrays, character vectors, and cell arrays of character vectors to numeric values. Text can represent hexadecimal or binary values, though when you convert them to numbers they are stored as decimal values. You can also convert text representing dates and time to datetime or duration values, which can be treated like numeric values.

Double-Precision Values

The recommended way to convert text to double-precision values is to use the str2double function. It can convert character vectors, string arrays, and cell arrays of character vectors.

For example, create a character vector using single quotes and convert it to the number it represents.

X = str2double('3.1416')

X = 
3.1416

If the input argument is a string array or cell array of character vectors, then str2double converts it to a numeric array having the same size. You can create strings using double quotes. (Strings have the string data type, while character vectors have the char data type.)

str = ["2.718","3.1416";
       "137","0.015"]

str = 2x2 string
    "2.718"    "3.1416"
    "137"      "0.015" 

   X = str2double(str)

X = 2×2

    2.7180    3.1416
  137.0000    0.0150

The str2double function can convert text that includes commas (as thousands separators) and decimal points. For example, you can use str2double to convert the Balance variable in the table below. Balance represents numbers as strings, using a comma as the thousands separator.

load balances
balances

balances=3×2 table
    Customer       Balance  
    _________    ___________

    "Diaz"       "13,790.00"
    "Johnson"    "2,456.10" 
    "Wu"         "923.71"   

T.Balance = str2double(T.Balance)

T=3×2 table
    Customer     Balance
    _________    _______

    "Diaz"        13790 
    "Johnson"    2456.1 
    "Wu"         923.71 

If str2double cannot convert text to a number, then it returns a NaN value.

While the str2num function can also convert text to numbers, it is not recommended. str2num uses the eval function, which can cause unintended side effects when the text input includes a function name. To avoid these issues, use str2double.

As an alternative, you can convert strings to double-precision values using the double function. If the input is a string array, then double returns a numeric array that has the same size, just as str2double does. However, if the input is a character vector, then double converts the individual characters to numbers representing their Unicode® values.

X = double("3.1416")

X = 
3.1416

X = double('3.1416')

X = 1×6

    51    46    49    52    49    54

This list summarizes the best practices for converting text to numeric values.

• To convert text to numeric values, use the str2double function. It treats string arrays, character vectors, and cell arrays of character vectors consistently.

• You can also use the double function for string arrays. However, it treats character vectors differently.

• Avoid str2num. It calls the eval function which can have unintended consequences.

Hexadecimal and Binary Values

You can represent hexadecimal and binary numbers as text or as literals. When you write them as literals, you must use the 0x and 0b prefixes. When you represent them as text and then convert them, you can use the prefixes, but they are not required.

For example, write a hexadecimal number as a literal. The prefix is required.

D = 0x3FF

D = uint16

1023

Then convert text representing the same value by using the hex2dec function. It recognizes the prefix but does not require it.

D = hex2dec('3FF')

D = 
1023

D = hex2dec('0x3FF')

D = 
1023

Convert text representing binary values using the bin2dec function.

D = bin2dec('101010')

D = 
42

D = bin2dec('0b101010')

D = 
42

Dates and Times

MATLAB provides the datetime and duration data types to store dates and times, and to treat them as numeric values. To convert text representing dates and times, use the datetime and duration functions.

Convert text representing a date to a datetime value. The datetime function recognizes many common formats for dates and times.

C = '2019-09-20'

C = 
'2019-09-20'

D = datetime(C)

D = datetime
   20-Sep-2019

You can convert arrays representing dates and times.

str = ["2019-01-31","2019-02-28","2019-03-31"]

str = 1x3 string
    "2019-01-31"    "2019-02-28"    "2019-03-31"

D = datetime(str)

D = 1x3 datetime
   31-Jan-2019   28-Feb-2019   31-Mar-2019

If you convert text to duration values, then use the hh:mm:ss or dd:hh:mm:ss formats.

D = duration('12:34:56')

D = duration
   12:34:56