join — Join text elements with delimiters in MATLAB and RunMat.
join(text, delimiter, dim) concatenates text along a chosen dimension and inserts delimiters between neighboring elements. Default dimension, delimiter broadcasting, and missing-string behavior follow MATLAB semantics.
Syntax
out = join(str)
out = join(str, delimiter)
out = join(str, dim)
out = join(str, delimiter, dim)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
str | Any | Yes | — | Input text (string/char/cell). |
delimiter | Any | Yes | " " | Delimiter scalar or delimiter array matching join shape constraints. |
dim | IntegerScalar | Yes | — | Positive dimension index to join along. |
delimiter | Any | Yes | — | Delimiter scalar or delimiter array matching join shape constraints. |
Returns
| Name | Type | Description |
|---|---|---|
out | Any | Joined text preserving join output container semantics. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:join:InputType | Input text is not a string array/scalar, char array, or cell array of text scalars. | join: input must be a string array, string scalar, character array, or cell array of character vectors |
RunMat:join:DelimiterType | Delimiter is not a supported text scalar/array/cell value. | join: delimiter must be a string, character vector, string array, or cell array of character vectors |
RunMat:join:DelimiterSize | Delimiter array shape does not match join shape constraints. | join: size of delimiter array must match the size of str, with the join dimension reduced by one |
RunMat:join:DimensionType | Dimension argument is not a positive integer scalar. | join: dimension must be a positive integer scalar |
RunMat:join:ArgCount | More than three total arguments are supplied. | join: too many input arguments |
RunMat:join:InternalError | Internal output container construction failed. | join: internal error |
How join works
- When you omit the dimension,
joinoperates along the last dimension whose size is not 1. If all dimensions are singleton, it uses dimension 2. - The default delimiter is a single space character. You can pass a scalar delimiter (string or character vector) or supply a string/cell array whose shape matches the input, with the join dimension reduced by one, to customise delimiters for each gap.
- Inputs may be string scalars, string arrays (including N-D), character arrays, or cell arrays of character vectors. Cell inputs return cell arrays; all other inputs return string scalars or string arrays.
- If any element participating in a join is the string
<missing>, the result for that slice is also<missing>, matching MATLAB’s missing propagation rules. - Joining along a dimension greater than
ndims(str)leaves the input unchanged. - The documented dimension is a positive integer-valued double scalar. Native typed-integer dimensions and the reversed
join(str,dim,delimiter)argument order are accepted only in RunMat compatibility mode.
Does RunMat run join on the GPU?
join executes on the CPU. When text or delimiters reside on the GPU, RunMat gathers them to host memory before performing the concatenation, ensuring identical results to MATLAB. Providers do not need to implement custom kernels for this builtin today.
GPU memory and residency
Text manipulation runs on the CPU. Automatic internal residency gathers transparently. Explicit resident typed-integer dimension controls are subject to the same RunMat-only compatibility gate as host typed dimensions.
Examples
Combine Strings In Each Row Of A Matrix
names = ["Carlos" "Sada"; "Ella" "Olsen"; "Diana" "Lee"];
fullNames = join(names)Expected output:
fullNames = 3×1 string
"Carlos Sada"
"Ella Olsen"
"Diana Lee"Insert A Custom Delimiter Between Elements
labels = ["x" "y" "z"; "a" "b" "c"];
joined = join(labels, "-")Expected output:
joined = 2×1 string
"x-y-z"
"a-b-c"Provide A Delimiter Array That Varies Per Row
str = ["x" "y" "z"; "a" "b" "c"];
delims = [" + " " = "; " - " " = "];
equations = join(str, delims)Expected output:
equations = 2×1 string
"x + y = z"
"a - b = c"Join Along A Specific Dimension
scores = ["Alice" "Bob"; "92" "88"; "85" "90"];
byColumn = join(scores, 1)Expected output:
byColumn = 1×2 string
"Alice 92 85" "Bob 88 90"Join A Cell Array Of Character Vectors
C = {'GPU', 'Accelerate'; 'VM', 'Interpreter'};
result = join(C, ", ")Expected output:
result = 2×1 cell
{'GPU, Accelerate'}
{'VM, Interpreter'}Join Using A Dimension Argument As The Second Input
words = ["RunMat"; "Accelerate"; "Planner"];
sentence = join(words, 1)Expected output:
sentence = "RunMat Accelerate Planner"Join Rows Of An Empty String Array
emptyRows = strings(2, 0);
out = join(emptyRows)Expected output:
out = 2×1 string
""
""Using join with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how join changes the result.
Run a small join example, explain the result, then change one input and compare the output.
FAQ
How does join choose the dimension when I do not specify one?⌄
It looks for the last dimension whose size is not 1 and joins along that axis. If every dimension has size 1, it uses dimension 2.
Can I use different delimiters between separate pairs of strings?⌄
Yes. Supply a string array or a cell array of character vectors with the same size as str, except that the join dimension must be one element shorter. Values of size 1 in other dimensions broadcast.
What happens when str contains <missing>?⌄
The result for that slice becomes <missing>. This matches MATLAB’s behaviour and ensures missing values propagate.
Can I pass GPU-resident text or delimiters?⌄
Values placed on the device by RunMat's internal planner gather transparently. Explicit resident numeric handles are not text; typed resident dimension controls are accepted only through the corresponding RunMat extension.
What if I request a dimension larger than ndims(str)?⌄
join returns the original text unchanged, matching MATLAB semantics.
Does join support numeric or logical inputs?⌄
No. Convert them to strings first (e.g., with string or compose), then call join.
How do I join every element into a single string?⌄
Specify the dimension explicitly. For column vectors, use join(str, 1); for higher dimensional arrays, choose the axis that spans the elements you want to combine.
Are cell array outputs returned as strings?⌄
No. When the input is a cell array, the output is a cell array of character vectors, keeping parity with MATLAB.
Related Strings functions
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · lower · pad · replace · replaceBetween · reverse · split · splitlines · strcat · strip · strjoin · strjust · strrep · strsplit · strtrim · upper
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
Core
blanks · char · 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
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 join is executed, line by line, in Rust.
- View the source for join 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.