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
str- Type
Any- Required
- Yes
- Description
- Input text (string/char/cell).
delimiter- Type
Any- Required
- Yes
- Default
" "- Description
- Delimiter scalar or delimiter array matching join shape constraints.
dim- Type
IntegerScalar- Required
- Yes
- Description
- Positive dimension index to join along.
delimiter- Type
Any- Required
- Yes
- Description
- Delimiter scalar or delimiter array matching join shape constraints.
Returns
out- Type
Any- Description
- Joined text preserving join output container semantics.
Errors
RunMat:join:TooManyOutputs- When
- More than one output is requested.
- Message
join: too many output arguments
RunMat:join:InputType- When
- Input text is not a string array/scalar, char array, or cell array of text scalars.
- Message
join: input must be a string array, string scalar, character array, or cell array of character vectors
RunMat:join:DelimiterType- When
- Delimiter is not a supported text scalar/array/cell value.
- Message
join: delimiter must be a string, character vector, string array, or cell array of character vectors
Behavior
When you omit the dimension, join operates 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 a typed missing string, the result for that slice is also missing. Literal <missing> text joins as ordinary text.
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.
Placement and effects
Executes on the CPU. Automatic internal residency gathers transparently; typed-integer dimensions and reversed join(str,dim,delimiter) syntax are mode-gated RunMat extensions.
This pure host operation may throw and may suspend at admitted gathers. It performs no callbacks, workspace/environment mutation, filesystem operations, randomness, or Clock reads. There is no GPU kernel, fusion route, or distributed support. VM and native calls share the canonical portable Runtime binding; these declarations are not execution evidence.
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.
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.
Current implementation frontier
Character arrays with non-singleton dimensions beyond two, including those inside cells and delimiter controls, reject before row extraction. String and cell array geometry follows the per-entry behavior described here.
Host text joining supports N-D string and cell geometry. Typed integer dimensions, reversed dimension/delimiter order, and explicit resident controls are the declared RunMat extensions. General managed output allocation and independent MATLAB/browser/native qualification remain open.
Examples
Combine Strings In Each Row Of A Matrix
names = ["Carlos" "Sada"; "Ella" "Olsen"; "Diana" "Lee"];
fullNames = join(names)Insert A Custom Delimiter Between Elements
labels = ["x" "y" "z"; "a" "b" "c"];
joined = join(labels, "-")Provide A Delimiter Array That Varies Per Row
str = ["x" "y" "z"; "a" "b" "c"];
delims = [" + " " = "; " - " " = "];
equations = join(str, delims)Join Along A Specific Dimension
scores = ["Alice" "Bob"; "92" "88"; "85" "90"];
byColumn = join(scores, 1)Join A Cell Array Of Character Vectors
C = {'GPU', 'Accelerate'; 'VM', 'Interpreter'};
result = join(C, ", ")Join Using A Dimension Argument As The Second Input
words = ["RunMat"; "Accelerate"; "Planner"];
sentence = join(words, 1)Join Rows Of An Empty String Array
emptyRows = strings(2, 0);
out = join(emptyRows)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 a missing string?⌄
The result for that slice is a typed missing string, displayed as <missing>. Literal text with that spelling remains nonmissing.
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
Source you can read
Every RunMat function's source is public. 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 a runtime that executes MATLAB-syntax code fast on any GPU. The runtime is free for individuals, including freelancers; students and faculty at an academic institution, for teaching or research there; contributors to an open-source project, for work on that project; organizations with 250 or fewer people and US$10M or less in annual revenue; and anyone, for non-production use. See runmat.com/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.