RunMat
GitHub

string — Convert numeric, logical, character, and text inputs into MATLAB-compatible string arrays.

string(x) converts scalar or array inputs into string arrays whose elements are string scalars. It follows MATLAB-compatible conversion behavior for numeric, logical, char, and existing string inputs.

Syntax

S = string(X)
S = string(X, encoding)
S = string(formatSpec, A...)

Inputs

NameTypeRequiredDefaultDescription
XAnyYes—Input value to convert to string array.
encodingStringScalarNo"UTF-8"Character encoding (UTF-8 aliases supported).
formatSpecAnyYes—Format specification text/cell/string array.
AAnyVariadic—Formatting data arguments.

Returns

NameTypeDescription
SAnyString scalar/array result.

Errors

IdentifierWhenMessage
RunMat:string:InvalidInputInput conversion/formatting/encoding constraints are violated.string: invalid input

How string works

  • Scalar inputs return a 1×1 string array containing the converted value.
  • Numeric and logical arrays preserve the original shape while converting each element.
  • Character arrays turn into columnar string arrays with one row per original row.
  • Cell arrays must contain text-like or scalar numeric values; each cell becomes one string scalar.
  • string(formatSpec, A1, ..., An) formats data using MATLAB-compatible % placeholders. Scalar format specs broadcast across array arguments and arrays of specs align element-wise.
  • Empty inputs yield empty string arrays that match MATLAB's dimension rules.
  • Unsupported types (structs, handle objects, events, functions) raise MATLAB-compatible errors.

Does RunMat run string on the GPU?

string is a residency sink. When the input contains GPU tensors, RunMat gathers the data back to host memory before performing the conversion. Providers do not need bespoke kernels—the CPU path is authoritative and ensures identical formatting across devices.

Examples

Converting A Numeric Scalar To A String

name = string(42)

Expected output:

name = "42"

Turning A Numeric Row Vector Into Strings

values = string([3.14159 2.71828 1.41421])

Expected output:

values = 1×3 string
    "3.1416"    "2.7183"    "1.4142"

Converting A Character Matrix Into A String Array

C = ['North '; 'South '; 'East  '; 'West  '];
regions = string(C)

Expected output:

regions = 4×1 string
    "North "
    "South "
    "East  "
    "West  "

Converting Logical Data To String Scalars

flags = string(logical([1 0 1 0]))

Expected output:

flags = 1×4 string
    "true"    "false"    "true"    "false"

Creating Strings From A Cell Array Of Mixed Scalars

C = {true, 17, "runmat"};
S = string(C)

Expected output:

S = 1×3 string
    "true"    "17"    "runmat"

Formatting Numbers With A Template

labels = string("Trial %d", 1:4)

Expected output:

labels = 1×4 string
    "Trial 1"    "Trial 2"    "Trial 3"    "Trial 4"

Converting GPU-Resident Numeric Data To Strings

G = gpuArray([10 20 30]);
labels = string(G)

Expected output:

labels = 1×3 string
    "10"    "20"    "30"

Using string with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how string changes the result.

Run a small string example, explain the result, then change one input and compare the output.

FAQ

Does string change the size of my array?⌄

No. Array-shaped inputs return string arrays with the same shape. Character arrays become column vectors where each row of characters maps to one string scalar.

How are floating-point numbers formatted?⌄

Floating-point values use MATLAB's short-g formatting (up to 12 significant digits) so the result matches disp output and is consistent across CPU and GPU inputs.

Can I use format specifiers like %0.2f?⌄

Yes. Provide a format string as the first argument and pass the values to substitute in the remaining arguments, e.g. string("Value %0.2f", A) or string(["X%02d" "Y%02d"], 1:2). Scalar format specs broadcast across vector inputs following MATLAB's rules.

What happens if I pass a GPU tensor?⌄

The builtin downloads the tensor using the active acceleration provider and then performs the conversion on the CPU. The resulting string array always resides in host memory.

Can I request a specific character encoding?⌄

RunMat currently supports UTF-8 (the default). Passing 'UTF-8', 'utf8', or 'system' yields the same behaviour. Other encodings raise a descriptive error.

Can I convert complex numbers or complex arrays?⌄

Yes. Complex scalars and arrays use MATLAB's a + bi formatting, with imaginary values rendered using the i suffix.

What happens with empty inputs?⌄

Empty inputs return empty string arrays following MATLAB's dimension rules—for example, string([]) yields a 0×0 string array, and string(char.empty(0,5)) yields a 0×1 string array.

Why does string error on structs or handle objects?⌄

MATLAB's string only supports text-like or scalar numeric types. Structs, objects, listeners, and other handle types cannot be converted automatically and therefore raise an error in RunMat as well.

How can I keep trailing spaces from character arrays?⌄

string preserves every character, including trailing spaces. Use strtrim afterwards if you want to remove padding.

Do existing string arrays change when passed to string?⌄

No. Existing string arrays pass through unchanged, so string(["a" "b"]) returns the same array.

Open-source implementation

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

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.

Getting started · Benchmarks · Pricing

Download RunMat

Download RunMat for full performance, or use RunMat in your browser for zero setup.

Download RunMatTry in your browser