RunMat
GitHub

View all functions

CategoryStrings: Core
GPUYes

What does the char function do in MATLAB / RunMat?

char converts its inputs into a character array. Numeric inputs are interpreted as Unicode code points, text inputs become rows of characters, and cell elements or string scalars are padded with spaces when necessary so every row in the result has the same width.

How does the char function behave in MATLAB / RunMat?

  • char(x) with no arguments returns a 0×0 character array.
  • Numeric arrays must be real integers. The output character array has the same shape (up to two dimensions) as the numeric input.
  • String scalars and character vectors become individual rows. Rows are padded on the right with spaces to match the longest row.
  • String arrays with one or two dimensions contribute one row per element using MATLAB's column-major ordering.
  • Cell arrays must contain character vectors or string scalars. Each element becomes exactly one row in the result.
  • Inputs may be mixed and are vertically concatenated in the order they appear.
  • Complex inputs are unsupported and raise MATLAB-compatible errors.

char Function GPU Execution Behaviour

char gathers GPU tensors back to host memory using the active RunMat Accelerate provider before performing any conversion. The resulting character array always resides in host memory; providers do not need to supply specialised kernels.

GPU residency in RunMat (Do I need gpuArray?)

You usually do not need to call gpuArray manually for char. The runtime recognises that this builtin materialises text on the host, gathers GPU tensors automatically, and keeps the character array in CPU memory. Wrap the result in gpuArray(char(...)) only when you explicitly want the characters back on the device for subsequent GPU pipelines.

Examples of using the char function in MATLAB / RunMat

Converting a string scalar to a character row

name = char("RunMat");

Expected output:

name =
    'RunMat'

Building a character matrix from multiple rows

rows = char("alpha", "beta");

Expected output:

rows =
    'alpha'
    'beta '

Transforming numeric codes to characters

codes = [77 65 84 76 65 66];
letters = char(codes);

Expected output:

letters =
    'MATLAB'

Padding a string array into a character matrix

animals = ["cat"; "giraffe"];
C = char(animals);

Expected output:

C =
    'cat   '
    'giraffe'

Creating rows from a cell array of character vectors

dirs = {'north', 'east', 'west'};
chart = char(dirs);

Expected output:

chart =
    'north'
    'east '
    'west '

Converting GPU-resident codes back to text

G = gpuArray([82 85 78 77 65 84]);
label = char(G);

Expected output:

label =
    'RUNMAT'

RunMat downloads the numeric data from the GPU before constructing the character array.

FAQ

Does char accept numeric arrays with more than two dimensions?

No. Numeric inputs must be scalars, vectors, or two-dimensional matrices. Higher-dimensional arrays raise an error so MATLAB's behaviour is preserved.

How are rows padded when lengths differ?

Each row is right-padded with space characters so every row in the result has the same width as the longest row that was produced.

Can I convert cell arrays that contain empty text?

Yes. Empty strings or character vectors become rows with zero columns; they still participate in padding when combined with longer rows.

What happens if a numeric value is not an integer?

The builtin rejects non-integer numeric values. Use round, floor, or uint32 beforehand if you need to convert floating-point values into valid code points.

Are code points above the Basic Multilingual Plane supported?

Yes. Any integer that represents a valid Unicode scalar value (0..0x10FFFF, excluding surrogates) is accepted and converted to the corresponding character.

Can char convert complex numbers?

No. Complex values are not supported because MATLAB also rejects them. Convert the data to real values before calling char.

Does char keep characters on the GPU?

No. After conversion the result is a CPU-resident character array. Use gpuArray(char(...)) if you need to move the result back to the device.

See Also

string, gpuArray, gather

Source & Feedback