What does the cellstr function do in MATLAB / RunMat?

cellstr converts character arrays, string arrays, or cell arrays of character vectors into a cell array whose elements are character vectors (1-by-N char arrays). Trailing spaces in character array rows are trimmed to match MATLAB behaviour.

How does the cellstr function behave in MATLAB / RunMat?

• cellstr(A) with a character array A returns an m × 1 cell array whose entries correspond to the rows of A, with trailing spaces removed from each row.
• cellstr(S) with a string array S returns a cell array of the same size; each string scalar is converted to a character vector.
• cellstr(C) with a cell array C normalises the contents so that every element becomes a character vector. String scalars are converted, existing character vectors are preserved, and any other type triggers an error just like MATLAB.
• String arrays of any dimensionality preserve their exact shape. Ordering follows MATLAB's column-major semantics so downstream indexing sees the expected elements.
• Empty character arrays result in empty cell arrays (for example, 0 × n char arrays map to 0 × 1 cells). Empty strings become "" character vectors stored in single-cell outputs.
• Missing string scalars are rendered as the literal '<missing>', matching MATLAB's textual representation.
• Inputs that are not text (numeric tensors, logical arrays, structs, GPU tensors, etc.) raise a MATLAB-compatible usage error.
• Cell elements must already be text. Any numeric, logical, or GPU value inside the cell raises an error so that downstream code never sees non-text rows.

cellstr Function GPU Execution Behaviour

cellstr is a host-only builtin. If the input or any nested cell elements contain GPU tensors, RunMat gathers them to the host before conversion (including nested elements inside cell arrays). The resulting cell array is always allocated in host memory. No provider hooks are required at this stage, but the GPU metadata keeps the runtime aware that residency does not propagate past this builtin.

Examples of using the cellstr function in MATLAB / RunMat

Converting a character matrix into a column cell array

A = ['apple '; 'berry '; 'citrus'];
C = cellstr(A);

Expected output:

C =
  3x1 cell array
    {'apple'}
    {'berry'}
    {'citrus'}

Removing trailing spaces automatically

words = ['a   '; 'b   '; 'c   '];
C = cellstr(words);

Expected output:

C =
  3x1 cell array
    {'a'}
    {'b'}
    {'c'}

Converting a string array while preserving shape

S = ["north" "south"; "east" "west"];
C = cellstr(S);

Expected output:

C =
  2x2 cell array
    {'north'}    {'south'}
    {'east'}     {'west'}

Normalising a cell array that mixes strings and character vectors

C = {"left", 'right'};
out = cellstr(C);

Expected output:

out =
  1x2 cell array
    {'left'}    {'right'}

Handling empty character arrays

emptyChars = char.empty(0, 5);
C = cellstr(emptyChars);
size(C)

Expected output:

ans =
     0     1

Converting a single string scalar

single = "RunMat";
C = cellstr(single);

Expected output:

C =
  1x1 cell array
    {'RunMat'}

Validating non-text inputs

try
    cellstr(42);
catch ME
    disp(ME.message)
end

Expected output:

cellstr: input must be a character array, string array, or cell array of character vectors

GPU residency in RunMat (Do I need gpuArray?)

No. cellstr executes on the host. If the input originates from the GPU (for example, a cell array whose elements were gathered lazily), RunMat performs the gather automatically before formatting the text. The output always resides on the CPU heap, mirroring MATLAB where cell arrays of text are CPU-managed containers.

FAQ

Does cellstr trim whitespace inside the text?

No. Only trailing spaces added by rectangular character arrays are removed. Interior spaces and tabs are preserved exactly as supplied.

What happens when a cell element is not text?

cellstr raises an error: every element must be a character vector or string scalar. This matches MATLAB and prevents silent conversion of unsupported data such as numeric arrays.

Can the output stay on the GPU?

Not yet. The resulting cell array always lives on the host. Future versions may add GPU-backed cell containers, in which case the GPU metadata in this builtin will be updated accordingly without breaking user code.

Are string arrays with missing values supported?

Yes. Missing string scalars (rendered as <missing>) convert to the character vector '<missing>' in the output cell array.

How are empty inputs handled?

Empty character arrays become empty cell arrays (0×1). Empty string arrays return empty cell arrays matching their size. Empty strings become single cells that contain a 1×0 character vector.

Does cellstr copy existing cell arrays?

Yes. The builtin returns a fresh cell array where each element is normalised to a character vector. Elements that are already character vectors are cloned so that downstream code can modify the result without mutating the source cell.