RunMat
GitHub

View all functions

CategoryStrings: Core
GPUYes

What does the str2double function do in MATLAB / RunMat?

str2double converts text representations of numbers into double-precision values. It accepts string scalars, string arrays, character vectors, character arrays, and cell arrays of character vectors. Each element is parsed independently; values that cannot be interpreted as real scalars become NaN.

How does the str2double function behave in MATLAB / RunMat?

  • Leading and trailing whitespace is ignored, as are padding spaces that MATLAB inserts in character arrays.
  • Text that contains a single finite real number returns that number. Text with additional characters, embedded operators, or multiple values results in NaN.
  • Scientific notation with e, E, d, or D exponents is supported ("1.2e3", "4.5D-6", etc.).
  • "Inf", "Infinity", and "NaN" (any letter case, with optional sign on Inf) map to IEEE special values.
  • Missing string scalars (displayed as <missing>) convert to NaN, matching MATLAB behaviour.
  • Character arrays return a column vector whose length equals the number of rows; cell arrays preserve their shape.

str2double Function GPU Execution Behaviour

str2double executes entirely on the CPU. If any argument is backed by a GPU buffer (for example, a cell array that still wraps GPU-resident character data), RunMat gathers the values first, parses the text on the host, and returns CPU-resident doubles. Providers do not need custom kernels for this builtin.

Examples of using the str2double function in MATLAB / RunMat

Convert a string scalar into a double

value = str2double("3.14159");

Expected output:

value = 3.14159

Convert every element of a string array

temps = ["12.5" "19.8" "not-a-number"];
data = str2double(temps);

Expected output:

data = 1×3
   12.5000   19.8000       NaN

Parse scientific notation text

result = str2double("6.022e23");

Expected output:

result = 6.0220e+23

Handle engineering exponents written with D

cap = str2double("4.7D-9");

Expected output:

cap = 4.7000e-09

Convert a character array one row at a time

chars = ['42   '; '  100'];
numbers = str2double(chars);

Expected output:

numbers = 2×1
    42
   100

Work with cell arrays of character vectors

C = {'3.14', 'NaN', '-Inf'};
values = str2double(C);

Expected output:

values = 1×3
    3.1400      NaN      -Inf

Detect invalid numeric text

status = str2double("error42");

Expected output:

status = NaN

Recognise special values Inf and NaN

special = str2double(["Inf"; "-Infinity"; "NaN"]);

Expected output:

special = 3×1
     Inf
    -Inf
     NaN

FAQ

What input types does str2double accept?

String scalars, string arrays, character vectors, character arrays, and cell arrays of character vectors or string scalars are supported. Other types raise an error so that mismatched inputs are caught early.

How are invalid or empty strings handled?

Invalid text—including empty strings, whitespace-only rows, or strings with extra characters—converts to NaN. This matches MATLAB, which uses NaN as a sentinel for failed conversions.

Does str2double evaluate arithmetic expressions?

No. Unlike str2num, str2double never calls the evaluator. Text such as "1+2" or "sqrt(2)" yields NaN instead of executing the expression, keeping the builtin safe for untrusted input.

Can str2double parse complex numbers?

No. Complex text like "3+4i" returns NaN. Use str2num when you need MATLAB to interpret complex literals.

Are engineering exponents with D supported?

Yes. Exponents that use d or D are rewritten to e automatically, so "1.0D3" converts to 1000.

How does str2double treat missing strings?

Missing strings produced with string(missing) display as <missing> and convert to NaN. You can detect them with ismissing before conversion if you need special handling.

Does locale affect parsing?

str2double honours digits, decimal points, and exponent letters only. Locale-specific grouping separators such as commas are not accepted, mirroring MATLAB's behaviour.

Will the result stay on the GPU when I pass gpuArray inputs?

No. The builtin gathers GPU-backed inputs to the host, parses them, and keeps the numeric result in host memory. Wrap the result with gpuArray(...) if you need to move it back to the device.

See Also

str2num, double, string, str2int

Source & Feedback