{
"title": "join",
"category": "strings/transform",
"keywords": [
"join",
"string join",
"concatenate strings",
"delimiters",
"cell array join",
"dimension join"
],
"summary": "Combine text across a specified dimension inserting delimiters between elements.",
"references": [
"https://www.mathworks.com/help/matlab/ref/join.html"
],
"gpu_support": {
"elementwise": false,
"reduction": false,
"precisions": [],
"broadcasting": "none",
"notes": "Executes on the CPU; GPU-resident inputs and delimiters are gathered before joining to ensure MATLAB-compatible behaviour."
},
"fusion": {
"elementwise": false,
"reduction": false,
"max_inputs": 2,
"constants": "inline"
},
"requires_feature": null,
"tested": {
"unit": "builtins::strings::transform::join::tests",
"integration": "builtins::strings::transform::join::tests::join_cell_array_of_char_vectors"
},
"description": "`join` concatenates text along a chosen dimension of a string array or a cell array of character vectors. It inserts delimiters between neighbouring elements and mirrors MATLAB semantics for default dimension selection, delimiter broadcasting, and handling of missing strings.",
"behaviors": [
"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 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."
],
"examples": [
{
"description": "Combine Strings In Each Row Of A Matrix",
"input": "names = [\"Carlos\" \"Sada\"; \"Ella\" \"Olsen\"; \"Diana\" \"Lee\"];\nfullNames = join(names)",
"output": "fullNames = 3×1 string\n \"Carlos Sada\"\n \"Ella Olsen\"\n \"Diana Lee\""
},
{
"description": "Insert A Custom Delimiter Between Elements",
"input": "labels = [\"x\" \"y\" \"z\"; \"a\" \"b\" \"c\"];\njoined = join(labels, \"-\")",
"output": "joined = 2×1 string\n \"x-y-z\"\n \"a-b-c\""
},
{
"description": "Provide A Delimiter Array That Varies Per Row",
"input": "str = [\"x\" \"y\" \"z\"; \"a\" \"b\" \"c\"];\ndelims = [\" + \" \" = \"; \" - \" \" = \"];\nequations = join(str, delims)",
"output": "equations = 2×1 string\n \"x + y = z\"\n \"a - b = c\""
},
{
"description": "Join Along A Specific Dimension",
"input": "scores = [\"Alice\" \"Bob\"; \"92\" \"88\"; \"85\" \"90\"];\nbyColumn = join(scores, 1)",
"output": "byColumn = 1×2 string\n \"Alice 92 85\" \"Bob 88 90\""
},
{
"description": "Join A Cell Array Of Character Vectors",
"input": "C = {'GPU', 'Accelerate'; 'Ignition', 'Interpreter'};\nresult = join(C, \", \")",
"output": "result = 2×1 cell\n {'GPU, Accelerate'}\n {'Ignition, Interpreter'}"
},
{
"description": "Join Using A Dimension Argument As The Second Input",
"input": "words = [\"RunMat\"; \"Accelerate\"; \"Planner\"];\nsentence = join(words, 1)",
"output": "sentence = \"RunMat Accelerate Planner\""
},
{
"description": "Join Rows Of An Empty String Array",
"input": "emptyRows = strings(2, 0);\nout = join(emptyRows)",
"output": "out = 2×1 string\n \"\"\n \"\""
}
],
"faqs": [
{
"question": "How does `join` choose the dimension when I do not specify one?",
"answer": "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."
},
{
"question": "Can I use different delimiters between separate pairs of strings?",
"answer": "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."
},
{
"question": "What happens when `str` contains `<missing>`?",
"answer": "The result for that slice becomes `<missing>`. This matches MATLAB’s behaviour and ensures missing values propagate."
},
{
"question": "Can I pass GPU-resident text or delimiters?",
"answer": "You can; RunMat gathers them to host memory automatically before performing the join."
},
{
"question": "What if I request a dimension larger than `ndims(str)`?",
"answer": "`join` returns the original text unchanged, matching MATLAB semantics."
},
{
"question": "Does `join` support numeric or logical inputs?",
"answer": "No. Convert them to strings first (e.g., with `string` or `compose`), then call `join`."
},
{
"question": "How do I join every element into a single string?",
"answer": "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."
},
{
"question": "Are cell array outputs returned as strings?",
"answer": "No. When the input is a cell array, the output is a cell array of character vectors, keeping parity with MATLAB."
}
],
"links": [
{
"label": "split",
"url": "./split"
},
{
"label": "compose",
"url": "./compose"
},
{
"label": "string",
"url": "./string"
},
{
"label": "erase",
"url": "./erase"
},
{
"label": "eraseBetween",
"url": "./erasebetween"
},
{
"label": "extractBetween",
"url": "./extractbetween"
},
{
"label": "lower",
"url": "./lower"
},
{
"label": "pad",
"url": "./pad"
},
{
"label": "replace",
"url": "./replace"
},
{
"label": "strcat",
"url": "./strcat"
},
{
"label": "strip",
"url": "./strip"
},
{
"label": "strrep",
"url": "./strrep"
},
{
"label": "strtrim",
"url": "./strtrim"
},
{
"label": "upper",
"url": "./upper"
}
],
"source": {
"label": "`crates/runmat-runtime/src/builtins/strings/transform/join.rs`",
"url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/transform/join.rs"
},
"gpu_residency": "No. Text manipulation currently runs on the CPU. If your text or delimiters were produced on the GPU, RunMat gathers them automatically so that you can call `join` without extra steps.",
"gpu_behavior": [
"`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."
]
}