num2str — Convert numeric values to formatted character arrays.
num2str formats real, complex, integer, and logical values with default, precision, or custom formatting.
Syntax
txt = num2str(A)
txt = num2str(A, p)
txt = num2str(A, formatSpec)
txt = num2str(A, 'local')
txt = num2str(A, p_or_format, 'local')Inputs
A- Type
Any- Required
- Yes
- Description
- Real or complex numeric or logical scalar, vector, or matrix.
p- Type
IntegerScalar- Required
- Yes
- Description
- General-format precision from 0 through 52.
formatSpec- Type
StringScalar- Required
- Yes
- Description
- Single-value printf-style f, e, or g format.
local- Type
StringScalar- Required
- Yes
- Description
- The local decimal-separator option.
p_or_format- Type
Any- Required
- Yes
- Description
- Precision or format string.
Returns
txt- Type
Any- Description
- Host character array of formatted numeric values.
Errors
RunMat:num2str:InvalidInput- When
- Input is not a supported numeric or logical scalar, vector, or matrix.
- Message
num2str: unsupported input type
RunMat:num2str:InvalidOption- When
- Options are malformed or too many arguments were supplied.
- Message
num2str: invalid option arguments
RunMat:num2str:InvalidPrecision- When
- Precision is non-finite, fractional, or outside 0 through 52.
- Message
num2str: invalid precision
Formatting and options
num2str(A) formats real, complex, integer, or logical values as a character array. The default general format uses up to 15 significant digits. num2str(A, p) accepts precision 0 through 52; num2str(A, formatSpec) accepts one numeric printf conversion using f/F, e/E, or g/G with supported width, sign, left-alignment and zero-padding flags. A format field width above 4096 is rejected before formatting.
All eight integer classes, including wide values above flintmax, are read from native storage. Complex integer components also retain exact decimal text. A numeric precision value is decoded and range checked; it does not change the input's storage class.
Vectors produce one text row. Matrices produce one text row per input row with aligned columns. An empty input with zero rows yields a 0-by-0 character array; zero columns and a nonzero row count retain that row count.
Locale, placement and effects
A final 'local' argument may be used alone or after precision/format. It selects a decimal separator from RUNMAT_DECIMAL_SEPARATOR, then locale environment values (LC_NUMERIC, RUNMAT_LOCALE, LANG). The output can therefore depend on the process environment; pin those settings for deterministic text.
Formatting runs on the host in native and browser runtimes. Automatic resident data is gathered through its owner. An explicit gpuArray input is a RunMat-only host-fallback form and is rejected in strict MATLAB compatibility mode before gathering. There is no GPU formatting kernel or fusion path; a gather may suspend.
The binding may throw for unsupported data, precision, format, options, dimensions or output count. It does not mutate workspace or environment and has no callback, filesystem, network, randomness or time effect.
Examples
Format a scalar with default precision
label = num2str(pi)Expected output:
'3.14159265358979'Select significant digits
digits = num2str(pi, 4)Expected output:
'3.142'Use a fixed-decimal format
row = num2str([1.234 5.678], '%.2f')Expected output:
'1.23 5.68'Align matrix columns
block = num2str([1 23 456; 78 9 10])Expected output:
' 1 23 456'; '78 9 10'Format complex numbers
z = num2str([3+4i 5-6i])Expected output:
'3 + 4i 5 - 6i'Use a local decimal separator
oldSeparator = getenv('RUNMAT_DECIMAL_SEPARATOR');
setenv('RUNMAT_DECIMAL_SEPARATOR', ',');
text = num2str(0.125, 'local');
if isempty(oldSeparator)
unsetenv('RUNMAT_DECIMAL_SEPARATOR');
else
setenv('RUNMAT_DECIMAL_SEPARATOR', oldSeparator);
endExpected output:
'0,125'Format explicit resident input on the host
G = gpuArray([10.5 20.5]); txt = num2str(G, '%.1f')Expected output:
'10.5 20.5'Using num2str with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how num2str changes the result.
Run a small num2str example, explain the result, then change one input and compare the output.
FAQ
Can I request more than 15 significant digits?⌄
Yes. The precision argument accepts 0 through 52; use a custom format for explicit decimal or exponent output.
Which format strings are supported?⌄
One f/F, e/E, or g/G conversion with supported width and +, -, or 0 flags. Unsupported formats raise an error.
Does the output have the same dimensions as the input?⌄
No. It is a padded character array: the number of rows follows the input matrix, while text formatting determines its width.
How are complex values rendered?⌄
The real and imaginary components use the selected precision and produce signed i notation.
What controls the 'local' decimal separator?⌄
RUNMAT_DECIMAL_SEPARATOR takes precedence; otherwise RunMat checks LC_NUMERIC, RUNMAT_LOCALE, and LANG.
What happens with nonnumeric input?⌄
Text, structs, objects, and handles are not numeric data and raise an input error. Use string(...) for general text conversion.
Can I convert the result to a string scalar?⌄
Yes. Use string(num2str(A)) when a string scalar is needed.
Related Strings functions
Core
blanks · char · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · sprintf · sscanf · str2double · 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 num2str is executed, line by line, in Rust.
- View the source for num2str 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.