num2str — Convert numeric values to character arrays in MATLAB and RunMat.
num2str(X, ...) converts numeric values to character arrays using default or custom formatting. Precision, complex formatting, and row-wise matrix output behavior follow MATLAB semantics.
Syntax
txt = num2str(A)
txt = num2str(A, p)
txt = num2str(A, formatSpec)
txt = num2str(A, arg2, "local")Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
A | Any | Yes | — | Numeric or logical scalar/vector/matrix input. |
A | Any | Yes | — | Numeric or logical input. |
p | IntegerScalar | Yes | 15 | General-format precision (0..52). |
formatSpec | StringScalar | Yes | — | Custom format such as "%0.3f" or "%.5g". |
arg2 | Any | No | — | Precision or format string. |
local | StringScalar | Yes | "local" | Locale-aware decimal separator option. |
Returns
| Name | Type | Description |
|---|---|---|
txt | Any | Character array containing formatted numeric values. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:num2str:InvalidInput | Input value is not a supported numeric/logical scalar, vector, or matrix. | num2str: unsupported input type |
RunMat:num2str:InvalidOption | Optional arguments are malformed or too many were supplied. | num2str: invalid option arguments |
RunMat:num2str:InvalidPrecision | Precision argument is non-finite, non-integer, or out of range. | num2str: invalid precision |
RunMat:num2str:InvalidFormat | Custom format string is unsupported or malformed. | num2str: unsupported format string |
RunMat:num2str:InternalError | Internal char-array assembly failed. | num2str: internal error |
How num2str works
- Default formatting uses up to 15 significant digits with MATLAB-style
gbehaviour (switching to scientific notation when needed). num2str(x, p)formats usingpsignificant digits (0 ≤ p ≤ 52).num2str(x, fmt)accepts a single-numberprintf-style format such as'%0.3f','%10.4e', or'%.5g'. Width,+,-, and0flags are supported.- A trailing
'local'argument switches the decimal separator to the one inferred from the active locale (or theRUNMAT_DECIMAL_SEPARATORenvironment variable). - Vector inputs return single-row character arrays; matrices return one textual row per numeric row.
- Empty matrices return empty character arrays that match MATLAB's dimension rules.
- All eight integer classes and logical input are accepted. Integer values are formatted from native storage, including values outside the exact binary64 range.
- The numeric precision argument accepts every integer class and is validated exactly before conversion to a formatting control.
- Non-numeric types raise MATLAB-compatible errors.
Does RunMat run num2str on the GPU?
When the input resides on the GPU, RunMat gathers the data back to host memory using the active RunMat Accelerate provider before applying the formatting logic. The formatted character array always lives on the CPU, so providers do not need to implement specialised kernels.
Examples
Converting A Scalar With Default Precision
label = num2str(pi)Expected output:
label =
'3.14159265358979'Formatting With A Specific Number Of Significant Digits
digits = num2str(pi, 4)Expected output:
digits =
'3.142'Using A Custom Format String
row = num2str([1.234 5.678], '%.2f')Expected output:
row =
'1.23 5.68'Displaying A Matrix With Column Alignment
block = num2str([1 23 456; 78 9 10])Expected output:
block =
' 1 23 456'
'78 9 10'Formatting Complex Numbers
z = num2str([3+4i 5-6i])Expected output:
z =
'3 + 4i 5 - 6i'Respecting Locale-Specific Decimal Separators
text = num2str(0.125, 'local')Converting GPU-Resident Data
G = gpuArray([10.5 20.5]);
txt = num2str(G, '%.1f')Expected output:
txt =
'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 digits?⌄
Yes. Pass a precision between 0 and 52 to control the number of significant digits, e.g. num2str(x, 20).
What format strings are supported?⌄
RunMat supports single-value printf conversions using %f, %e, %E, %g, and %G, including optional width, +, -, and 0 flags. Unsupported flags raise descriptive errors.
Does num2str alter the size of my array?⌄
No. The textual result has the same number of rows as the input and aligns each column with spaces.
How are complex numbers rendered?⌄
Real and imaginary components are formatted separately using the selected precision. The result is a + bi or a - bi, with zero real parts simplifying to bi.
How does the 'local' flag work?⌄
num2str(..., 'local') replaces the decimal point with the separator inferred from the active locale. You can override the detected character with RUNMAT_DECIMAL_SEPARATOR, e.g. RUNMAT_DECIMAL_SEPARATOR=,.
What happens with non-numeric inputs?⌄
Passing structs, objects, handles, or text raises a MATLAB-compatible error. Convert the data to numeric form first or use string for rich text conversions.
What is num2str in MATLAB?⌄
— num2str(A) converts a numeric value A (scalar, vector, or matrix) into a MATLAB char array so you can display, concatenate, or log it as text. Each row of A becomes one row of text, and values are rendered in MATLAB's short g style by default. RunMat implements the same signature so MATLAB code that builds labels with num2str runs unchanged.
How do I control the format or precision of num2str?⌄
— Pass either a precision (the number of significant digits) or an explicit printf-style format string as the second argument. For example, num2str(pi, 8) returns '3.1415927', num2str(pi, '%.3f') returns '3.142', and num2str(1234.5, '%10.2e') right-aligns the value in scientific notation. Width and the +, -, and 0 flags are all honoured.
How do I convert a number to a string with num2str?⌄
— Call s = num2str(A). The result is a char array (MATLAB's classical string). If you need a modern string scalar, wrap the result with string(...); for a round-trippable MATLAB literal, use mat2str; for full printf-style control over multiple variables, reach for sprintf.
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
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. 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 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.