split — Split text values into substrings using delimiter rules with MATLAB-compatible container behavior.
split(text) breaks text into substrings separated by delimiters across string, char, and cell-text inputs. It follows MATLAB-compatible default-delimiter and output-container behavior, including whitespace splitting when no delimiter is provided.
Syntax
newStr = split(str)
newStr = split(str, delimiter)
[newStr, match] = split(str, delimiter, dim)
newStr = split(str, delimiter, Name, Value, ...)
newStr = split(str, Name, Value, ...)Inputs
str- Type
Any- Required
- Yes
- Description
- Input text scalar/array/cell to split.
delimiter- Type
Any- Required
- Yes
- Description
- Delimiter scalar/array/cell.
dim- Type
IntegerScalar- Required
- Yes
- Description
- Positive dimension along which output substrings are oriented.
Name- Type
StringScalar- Required
- Yes
- Description
- Option name (`CollapseDelimiters` or `IncludeDelimiters`).
Value- Type
Any- Required
- Variadic
- Description
- Option values and additional Name/Value pairs.
Returns
newStr- Type
Any- Description
- String or cell array containing split tokens.
match- Type
Any- Description
- String or cell array containing the delimiters at which splitting occurred.
Returned values from split depend on how many outputs the caller requests.
Errors
RunMat:split:TooManyOutputs- When
- More than two outputs are requested.
- Message
split: too many output arguments
RunMat:split:InvalidInput- When
- First argument is not a string scalar/array, char array, or cell array of text scalars.
- Message
split: first argument must be a string scalar, string array, character array, or cell array of character vectors
RunMat:split:DelimiterType- When
- Delimiter input is not a supported text scalar/array/cell.
- Message
split: delimiter input must be a string scalar, string array, character array, or cell array of character vectors
Behavior
The default delimiter is whitespace (isspace), and consecutive whitespace is treated as a single separator (equivalent to 'CollapseDelimiters', true).
When you supply explicit delimiters, they can be a string scalar, string array, character array (rows), or a cell array of character vectors. Delimiters are matched left to right and the longest delimiter wins when several candidates match at the same position.
RunMat mode retains the advanced 'CollapseDelimiters' and 'IncludeDelimiters' options behind one compatibility gate; they are not presented as MATLAB-compatible split options.
A documented positive double dim controls output orientation. Typed integer dimensions are available only in RunMat mode because the compatibility target does not enumerate their storage classes. RunMat rejects dimensions above its supported rank ceiling of 1024 before allocating shape metadata.
Without an explicit dimension, scalar input produces an N×1 string column, a column vector produces M×N, and a multidimensional input appends the token dimension. An explicit dimension inserts or replaces that dimension using column-major ordering.
When requested, the second output contains the matched delimiters with the same orientation rules. Padding slots contain typed missing strings, displayed as <missing>.
Missing string scalars propagate unchanged.
Placement and effects
Text is host-only. Automatically placed double dimension controls gather transparently; explicit resident dimensions and typed integer dimensions are separately 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 and delimiters are host-only. Automatically placed double dimensions gather transparently; explicit resident dimensions are compatibility-gated before gather.
split executes on the CPU. Numeric resident values in text or delimiter roles reject without provider access; only an admitted dimension control may gather.
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.
Current input text geometry is scalar or two-dimensional; non-singleton dimensions beyond two reject before flattening. Output orientation may add a token axis, and two output prefixes are supported. General N-D input support and managed text allocation remain incomplete.
Examples
Split A String On Whitespace
txt = "RunMat Accelerate Planner";
pieces = split(txt)Split A String Using A Custom Delimiter
csv = "alpha,beta,gamma";
tokens = split(csv, ",")Include Delimiters In The Output
expr = "A+B-C";
segments = split(expr, ["+", "-"], "IncludeDelimiters", true)Preserve Empty Segments When CollapseDelimiters Is False
values = "one,,three,";
parts = split(values, ",", "CollapseDelimiters", false)Split Each Row Of A Character Array
rows = char("GPU Accelerate", "VM Interpreter");
result = split(rows)Split Elements Of A Cell Array
C = {'RunMat Snapshot'; "Fusion Planner"};
out = split(C, " ")Handle Missing String Inputs
names = ["RunMat"; string(missing); "Accelerate Engine"];
split_names = split(names)Using split with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how split changes the result.
Run a small split example, explain the result, then change one input and compare the output.
FAQ
What delimiters does split use by default?⌄
When you omit the second argument, split treats any Unicode whitespace as a delimiter and collapses consecutive whitespace runs so they produce a single split point.
How do explicit delimiters change the defaults?⌄
Providing explicit delimiters switches the internal collapse default to false. RunMat mode can override it with the compatibility-gated advanced option.
What happens when 'IncludeDelimiters' is true?⌄
This is a RunMat-mode extension. Matched delimiters are inserted between tokens in original order, with missing values used for padding.
How is the output sized for string arrays?⌄
Default orientation follows the documented input-shape rules: scalar input becomes N×1, a column vector becomes M×N, and multidimensional input gains a trailing token dimension. An explicit positive dimension controls where that token axis is placed.
How does split handle missing strings?⌄
Typed missing string scalars propagate unchanged. Padding slots also contain typed missing strings; literal <missing> text is split as ordinary text.
Can I provide empty delimiters?⌄
No. Empty delimiters are disallowed, matching MATLAB's input validation. Specify at least one character per delimiter.
Which argument types are accepted as delimiters?⌄
You may pass string scalars, string arrays, character arrays (each row is a delimiter), or cell arrays containing string scalars or character vectors.
How is split different from strsplit?⌄
split is the vectorized string-focused builtin in RunMat. Use strsplit when you need the MATLAB-style scalar-text API with optional matches output and DelimiterType handling.
Related Strings functions
Transform
append · deblank · erase · eraseBetween · erasePunctuation · eraseURLs · extractAfter · extractBefore · extractBetween · insertAfter · insertBefore · join · lower · pad · replace · replaceBetween · reverse · 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 split is executed, line by line, in Rust.
- View the source for split 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.