str2double — Convert text representations of numbers into double-precision values with MATLAB-compatible parsing rules.
str2double parses numeric text into double-precision values across string, char, and cellstr-style inputs. Elements that cannot be parsed as real numeric scalars return NaN, matching MATLAB behavior.
Syntax
X = str2double(str)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
str | Any | Yes | — | String, character, or cell-array text input to parse. |
Returns
| Name | Type | Description |
|---|---|---|
X | NumericArray | Parsed double values; invalid parses become NaN. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:str2double:InvalidInput | Input is not a supported text container. | str2double: input must be a string array, character array, or cell array of character vectors |
RunMat:str2double:InvalidCellElement | Cell array contains non-text or non-scalar text entries. | str2double: cell array elements must be character vectors or string scalars |
RunMat:str2double:InternalError | Internal tensor assembly failed while building parsed output. | str2double: internal error |
How str2double works
- 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, orDexponents is supported ("1.2e3","4.5D-6", etc.). "Inf","Infinity", and"NaN"(any letter case, with optional sign onInf) map to IEEE special values.- Missing string scalars (displayed as
<missing>) convert toNaN, matching MATLAB behaviour. - Character arrays return a column vector whose length equals the number of rows; cell arrays preserve their shape.
Does RunMat run str2double on the GPU?
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
Convert a string scalar into a double
value = str2double("3.14159")Expected output:
value = 3.14159Convert 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 NaNParse scientific notation text
result = str2double("6.022e23")Expected output:
result = 6.0220e+23Handle engineering exponents written with D
cap = str2double("4.7D-9")Expected output:
cap = 4.7000e-09Convert a character array one row at a time
chars = ['42 '; ' 100'];
numbers = str2double(chars)Expected output:
numbers = 2×1
42
100Work with cell arrays of character vectors
C = {'3.14', 'NaN', '-Inf'};
values = str2double(C)Expected output:
values = 1×3
3.1400 NaN -InfDetect invalid numeric text
status = str2double("error42")Expected output:
status = NaNRecognise special values Inf and NaN
special = str2double(["Inf"; "-Infinity"; "NaN"])Expected output:
special = 3×1
Inf
-Inf
NaNUsing str2double with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how str2double changes the result.
Run a small str2double example, explain the result, then change one input and compare the output.
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.
Related Strings functions
Core
char · compose · num2str · sprintf · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp
Search
contains · endsWith · startsWith · strfind
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how str2double is executed, line by line, in Rust.
- View the source for str2double in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.