str2double — Parse numeric text into real double values.
str2double parses scalar text and text containers without evaluating expressions.
Syntax
X = str2double(str)Inputs
str- Type
Any- Required
- Yes
- Description
- String, character, or cell-array text to parse.
Returns
X- Type
NumericArray- Description
- Host double values; invalid numeric text becomes NaN.
Errors
RunMat:str2double:InvalidInput- When
- Input is not a supported text container.
- Message
str2double: input must be a string array, character array, or cell array of character vectors
RunMat:str2double:InvalidCellElement- When
- Cell array contains non-text or non-scalar text entries.
- Message
str2double: cell array elements must be character vectors or string scalars
RunMat:str2double:InternalError- When
- Internal tensor assembly failed while building parsed output.
- Message
str2double: internal error
RunMat:str2double:TooManyOutputs- When
- More than one output is requested.
- Message
str2double: too many output arguments
Parsing
str2double(str) parses a string scalar or array, a character array, or a cell array of scalar text. It returns real double values; invalid or empty numeric text becomes NaN. It does not evaluate arithmetic expressions.
Leading and trailing spaces, e/E and d/D scientific exponents, and case-insensitive Inf, Infinity, and NaN are supported. Complex text and locale-specific thousands separators are not parsed.
String arrays and cell arrays retain their shape. A character array contributes one parsed value per row and yields a column vector. A cell element that is not a character row or scalar string raises an error.
Placement and errors
Parsing executes on the host in native and browser runtimes. Numeric inputs, including integer or GPU-resident numeric values, reject before provider access; there is no numeric-to-text conversion or GPU parsing kernel. The result is a host double value.
The function is pure but may throw for an unsupported container or cell element. A supported nested-value gather may suspend. It has no callback, workspace, filesystem, network, random, or time effect.
Examples
Parse a string scalar
value = str2double("3.14159")Expected output:
value = 3.14159Parse each string-array element
temps = ["12.5" "19.8" "not-a-number"]; data = str2double(temps)Expected output:
data = [12.5 19.8 NaN]Parse scientific notation
result = str2double("6.022e23")Expected output:
result = 6.022e23Parse a D exponent
cap = str2double("4.7D-9")Expected output:
cap = 4.7e-9Parse character-array rows
chars = ['42 '; ' 100']; numbers = str2double(chars)Expected output:
numbers = [42; 100]Parse a cell array of character vectors
C = {'3.14', 'NaN', '-Inf'}; values = str2double(C)Expected output:
values = [3.14 NaN -Inf]Detect invalid numeric text
status = str2double("error42")Expected output:
status = NaNParse Inf and NaN
special = str2double(["Inf"; "-Infinity"; "NaN"])Expected output:
special = [Inf; -Inf; NaN]Using 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 happens when text is not a number?⌄
The corresponding result is NaN; an unsupported input container instead raises an error.
Does str2double evaluate expressions?⌄
No. Expressions such as 1+2 do not execute and parse as NaN. Use str2num only when expression evaluation is intended.
Can it parse complex numbers?⌄
The current scalar parser returns real double values; complex text parses as NaN.
How are missing and empty strings handled?⌄
Empty, whitespace-only, and missing-string text parses as NaN. An invalid cell element type raises an error instead.
Does locale change numeric parsing?⌄
No. The parser uses a period as the decimal separator and does not accept locale-specific grouping commas.
Are D exponents accepted?⌄
Yes. A d or D exponent is interpreted as an e exponent.
Are GPU inputs parsed on the device?⌄
No. Numeric GPU values are not text and reject before provider access.
Related Strings functions
Core
blanks · char · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Search
contains · endsWith · matches · startsWith · strfind
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.