char — Convert numeric codes and text values into character arrays in MATLAB and RunMat.
char converts inputs into a character array. Numeric inputs are interpreted as code points, and text inputs are padded as needed so output rows share width, following MATLAB and RunMat conversion semantics.
Syntax
C = char()
C = char(X)
C = char(X...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
X | Any | Yes | — | Input value to convert into character data. |
X... | Any | Variadic | — | Multiple inputs converted row-wise and padded. |
Returns
| Name | Type | Description |
|---|---|---|
C | Any | Character array result. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:char:InvalidInput | Input type cannot be converted to character data. | char: invalid input |
RunMat:char:InvalidCodePoint | Numeric input cannot be represented by RunMat's scalar-value character storage. | char: numeric input cannot be represented as a RunMat character |
RunMat:char:InvalidDimension | Array inputs are not 2-D (or trailing singleton dimensions). | char: inputs must be 2-D |
RunMat:char:InternalError | Internal character array construction failed. | char: internal error |
How char works
char(x)with no arguments returns a0×0character array.- Real numeric values are truncated toward zero and clamped to the UTF-16 code-unit range 0 through 65535. All eight integer classes are read from exact native storage.
- RunMat's character storage cannot yet represent isolated UTF-16 surrogate code units; those inputs produce an explicit error instead of silently changing the value.
- Logical inputs and interactive resident numeric inputs are separately mode-gated RunMat extensions.
- 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.
Does RunMat run char on the GPU?
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 memory and residency
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
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'Using char with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how char changes the result.
Run a small char example, explain the result, then change one input and compare the output.
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.
Related Strings functions
Core
blanks · compose · convertCharsToStrings · convertContainedStringsToChars · convertStringsToChars · genvarname · int2str · isletter · isspace · isStringScalar · isstrprop · mat2str · native2unicode · newline · num2str · sprintf · sscanf · str2double · str2num · strcmp · strcmpi · string · string.empty · strings · strlength · strncmp · strncmpi · strtok · unicode2native
Text Analytics
addDependencyDetails · addEntityDetails · addLemmaDetails · addPartOfSpeechDetails · addSentenceDetails · addTypeDetails · bagOfNgrams · bagOfWords · cosineSimilarity · doc2sequence · encode · extractFileText · extractHTMLText · fastTextWordEmbedding · findElement · getAttribute · htmlTree · ind2word · isVocabularyWord · normalizeWords · readWordEmbedding · removeLongWords · removeShortWords · removeStopWords · removeWords · stopWords · tokenDetails · tokenizedDocument · trainWordEmbedding · vaderSentimentScores · vec2word · word2ind · word2vec · wordEncoding · writeWordEmbedding
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
Search
contains · endsWith · matches · startsWith · strfind
Pattern
digitsPattern · lettersPattern · pattern · regexpPattern · textBoundary · wildcardPattern
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how char is executed, line by line, in Rust.
- View the source for char in Rust on GitHub
- Learn how the RunMat 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 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.