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.

How num2str works in RunMat

• 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 num2str runs 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

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.

Related functions to explore

These functions work well alongside num2str. Each page has runnable examples you can try in the browser.

sprintf, string, str2double, char, compose, strcmp, strcmpi, string.empty, strings, strlength, strncmp

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