########################################################################

##

## Copyright (C) 2009-2026 The Octave Project Developers

##

## See the file COPYRIGHT.md in the top-level directory of this

## distribution or <https://octave.org/copyright/>.

##

## This file is part of Octave.

##

## Octave is free software: you can redistribute it and/or modify it

## under the terms of the GNU General Public License as published by

## the Free Software Foundation, either version 3 of the License, or

## (at your option) any later version.

##

## Octave is distributed in the hope that it will be useful, but

## WITHOUT ANY WARRANTY; without even the implied warranty of

## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

## GNU General Public License for more details.

##

## You should have received a copy of the GNU General Public License

## along with Octave; see the file COPYING. If not, see

## <https://www.gnu.org/licenses/>.

##

########################################################################

## -*- texinfo -*-

## @deftypefn {} {[@var{cstr}] =} strsplit (@var{str})

## @deftypefnx {} {[@var{cstr}] =} strsplit (@var{str}, @var{del})

## @deftypefnx {} {[@var{cstr}] =} strsplit (@dots{}, @var{name}, @var{value})

## @deftypefnx {} {[@var{cstr}, @var{matches}] =} strsplit (@dots{})

## Split the string @var{str} using the delimiters specified by @var{del} and

## return a cell string array of substrings.

##

## If a delimiter is not specified the string is split at whitespace

## @code{@{" ", "\f", "\n", "\r", "\t", "\v"@}}. Otherwise, the delimiter,

## @item @var{delimitertype} which may take the value of @qcode{"simple"}

## (default) or @nospell{@qcode{"regularexpression"}}. A simple delimiter

## matches the text exactly as written. Otherwise, the syntax for regular

## expressions outlined in @code{regexp} is used.

## @end itemize

##

## The optional second output, @var{matches}, returns the delimiters which were

## matched in the original string.

##

## Examples with simple delimiters:

##

## @example

## strsplit ("a b c")

## @xresult{}

## @{

## [1,1] = a

## [1,2] = b

## [1,3] = c

## @}

##

## strsplit ("a,b,c", ",")

## @xresult{}

## @{

## [1,1] = a

## [1,2] = b

## [1,3] = c

## @}

##

## strsplit ("a foo b,bar c", @{" ", ",", "foo", "bar"@})

## strsplit ("a,,b, c", @{",", " "@}, "collapsedelimiters", false)

## @xresult{}

## @{

## [1,1] = a

## [1,2] =

## [1,3] = b

## [1,4] =

## [1,5] = c

## @}

##

## @end example

##

## Examples with @nospell{regularexpression} delimiters:

##

## @smallexample

## strsplit ("a foo b,bar c", ',|\s|foo|bar', ...

## "delimitertype", "regularexpression")

## @xresult{}

## @{

## [1,1] = a

## [1,2] = b

## [1,3] = c

## @}

##

## strsplit ("a,,b, c", '[, ]', "collapsedelimiters", false, ...

## "delimitertype", "regularexpression")

## @xresult{}

## @{

## [1,1] = a

## [1,2] =

## [1,3] = b

## [1,4] =

## [1,5] = c

## @}

##

## strsplit ("a,\t,b, c", @{',', '\s'@}, "delimitertype", "regularexpression")

## strsplit ("a,\t,b, c", @{',', ' ', '\t'@}, "collapsedelimiters", false)

## @xresult{}

## @{

## [1,1] = a

## [1,2] =

## [1,3] =

## [1,4] = b

## [1,5] =

## [1,6] = c

## @}

## @end smallexample

##

## @seealso{ostrsplit, strjoin, strtok, regexp}

## @end deftypefn

function [cstr, matches] = strsplit (str, del, varargin)

args.collapsedelimiters = true;

args.delimitertype = "simple";

[reg, params] = parseparams (varargin);

if (nargin < 1)

print_usage ();

elseif (numel (reg) > 1)

print_usage ();

elseif (numel (reg) == 1)

## This is undocumented behavior to accept a logical 3rd arg.

if (islogical (reg{1}))

args.collapsedelimiters = reg{1};

else

print_usage ();

endif

endif

fields = fieldnames (args);

for n = 1:2:numel (params)

if (any (strcmpi (params{n}, fields)))

args.(lower (params{n})) = params{n+1};

elseif (ischar (varargin{n}))

error ("Octave:strsplit:invalid_parameter_name",

"strsplit: invalid parameter name, '%s'", varargin{n});

else

print_usage ();

endif

endfor

## Save the length of the "delimitertype" parameter

length_deltype = length (args.delimitertype);

if (nargin == 1 || (nargin > 1 && islogical (del)))

if (nargin > 1)

## Second input is the "collapsedelimiters" parameter

args.collapsedelimiters = del;

endif

## Set proper default for the delimiter type

if (strncmpi (args.delimitertype, "simple", length_deltype))

del = {" ", "\f", "\n", "\r", "\t", "\v"};

else

del = '\s';

endif

endif

if (! ischar (str) || (! ischar (del) && ! iscellstr (del)))

error ("strsplit: S and DEL must be string values");

elseif (! isempty (str) && ! isrow (str))

error ("strsplit: S must be a char row vector");

elseif (! isscalar (args.collapsedelimiters))

error ("strsplit: COLLAPSEDELIMITERS must be a scalar value");

endif

if (strncmpi (args.delimitertype, "simple", length_deltype))

is_simple = true;

elseif (strncmpi (args.delimitertype, "regularexpression", length_deltype))

is_simple = false;

else

error ("Octave:strsplit:invalid_delimitertype", "strsplit: Invalid DELIMITERTYPE");

endif

if (is_simple)

if (iscellstr (del))

del = cellfun ('do_string_escapes', del, "uniformoutput", false);

else

del = do_string_escapes (del);

endif

## Escape characters which have a special meaning in regexp.

del = regexprep (del, '([{}()[\]^$.*?+|\\])', '\\$1');

endif

if (isempty (str))

cstr = {str};

else

if (iscellstr (del))

del = sprintf ("%s|", del{:});

del(end) = [];

endif

if (args.collapsedelimiters)

del = [ "(" del ")+" ];

endif

[cstr, matches] = regexp (str, del, "split", "match");

endif

## Split on all whitespace.

## Split on "ain".

## Split on " " and "ain" (treating multiple delimiters as one).

## Split on " " and "ain", and treat multiple delimiters separately.

## Test "match" for consecutive delmiters

## Compatibility

## Test input validation