What does the string function do in MATLAB / RunMat?

string(x) converts scalars, arrays, and text-like inputs into MATLAB string arrays whose elements are string scalars. Numeric and logical values are formatted using MATLAB's short-g style, character arrays are split by row, and existing string arrays pass through unchanged.

How does the string function behave in MATLAB / RunMat?

• 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.

string Function GPU Execution Behaviour

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 of using the string function in MATLAB / RunMat

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"

RunMat gathers the GPU tensor to host memory automatically before formatting.

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.

See Also

char, cellstr, string.empty, strings