num2str — Convert numeric scalars, vectors, and matrices into MATLAB-style character arrays using general or custom formats.

num2str(x) converts numeric scalars, vectors, and matrices into a character array where each row of x becomes a row of text. Values use MATLAB's short-g formatting by default, and you can provide a precision or an explicit format specifier to control the output. Complex inputs produce a ± bi strings, and logical data is converted to 0 or 1.

Syntax

s = num2str(A)
s = num2str(A, precision)
s = num2str(A, format)

• A is the numeric input: scalar, vector, or matrix. Complex and logical values are accepted; each row of A becomes one row of output text.
• precision is an integer giving the maximum number of significant digits (default 5, matching MATLAB's short format). Values between 0 and 52 are accepted. Use it when you want concise output without hand-writing a printf string.
• format is a single-value printf-style format specifier such as '%10.2f', '%.3e', or '%.5g'. Width and the +, -, and 0 flags are supported; more elaborate formats belong to sprintf.
• Returns s, a MATLAB char array aligned so that every row is the same width. Wrap the result with string(s) if you need a modern string scalar instead.

How num2str works

• Default formatting uses up to 15 significant digits with MATLAB-style g behaviour (switching to scientific notation when needed).
• num2str(x, p) formats using p significant digits (0 ≤ p ≤ 52).
• num2str(x, fmt) accepts a single-number printf-style format such as '%0.3f', '%10.4e', or '%.5g'. Width, +, -, and 0 flags are supported.
• A trailing 'local' argument switches the decimal separator to the one inferred from the active locale (or the RUNMAT_DECIMAL_SEPARATOR environment 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.
• Non-numeric types raise MATLAB-compatible errors.

How RunMat runs 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'

FAQ

Related Strings functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how num2str works, line by line, in Rust.

• View num2str.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing