.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "STRING-SPLIT0" "1" "Nov 13, 2025" "4.2" "fish-shell"
.SH NAME
string-split0 \- split on zero bytes
.SH SYNOPSIS
.nf
\fBstring\fP \fBsplit\fP [(\fB\-f\fP | \fB\-\-fields\fP) \fIFIELDS\fP [\fB\-a\fP | \fB\-\-allow\-empty\fP]] [(\fB\-m\fP | \fB\-\-max\fP) \fIMAX\fP] [\fB\-n\fP | \fB\-\-no\-empty\fP]
             [\fB\-q\fP | \fB\-\-quiet\fP] [\fB\-r\fP | \fB\-\-right\fP] \fISEP\fP [\fISTRING\fP \&...]
\fBstring\fP \fBsplit0\fP [(\fB\-f\fP | \fB\-\-fields\fP) \fIFIELDS\fP [\fB\-a\fP | \fB\-\-allow\-empty\fP]] [(\fB\-m\fP | \fB\-\-max\fP) \fIMAX\fP] [\fB\-n\fP | \fB\-\-no\-empty\fP]
              [\fB\-q\fP | \fB\-\-quiet\fP] [\fB\-r\fP | \fB\-\-right\fP] [\fISTRING\fP \&...]
.fi
.sp
.SH DESCRIPTION
.sp
\fBstring split\fP splits each \fISTRING\fP on the separator \fISEP\fP, which can be an empty string. If \fB\-m\fP or \fB\-\-max\fP is specified, at most MAX splits are done on each \fISTRING\fP\&. If \fB\-r\fP or \fB\-\-right\fP is given, splitting is performed right\-to\-left. This is only useful in combination with \fB\-m\fP or \fB\-\-max\fP\&. With \fB\-n\fP or \fB\-\-no\-empty\fP, empty results are excluded from consideration (e.g. \fBhello\en\enworld\fP would expand to two strings and not three). Exit status: 0 if at least one split was performed, or 1 otherwise.
.sp
Use \fB\-f\fP or \fB\-\-fields\fP to print out specific fields. FIELDS is a comma\-separated string of field numbers and/or spans. Each field is one\-indexed, and will be printed on separate lines. If a given field does not exist, then the command exits with status 1 and does not print anything, unless \fB\-\-allow\-empty\fP is used.
.sp
See also the \fB\-\-delimiter\fP option of the \fI\%read\fP command.
.sp
\fBstring split0\fP splits each \fISTRING\fP on the zero byte (NUL). Options are the same as \fBstring split\fP except that no separator is given.
.sp
\fBsplit0\fP has the important property that its output is not further split when used in a command substitution, allowing for the command substitution to produce elements containing newlines. This is most useful when used with Unix tools that produce zero bytes, such as \fBfind \-print0\fP or \fBsort \-z\fP\&. See split0 examples below.
.sp
Be aware that commandline arguments cannot include NULs, so you likely want to pass to \fBstring split0\fP via a pipe, not a command substitution.
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>_ string split . example.com
example
com

>_ string split \-r \-m1 / /usr/local/bin/fish
/usr/local/bin
fish

>_ string split \(aq\(aq abc
a
b
c

>_ string split \-\-allow\-empty \-f1,3\-4,5 \(aq\(aq abcd
a
c
d
.EE
.UNINDENT
.UNINDENT
.SS NUL Delimited Examples
.INDENT 0.0
.INDENT 3.5
.sp
.EX
>_ # Count files in a directory, without being confused by newlines.
>_ # Note: Don\(aqt use \(gastring split0 (find . \-print0)\(ga, because arguments cannot include NUL.
>_ count (find . \-print0 | string split0)
42

>_ # Sort a list of elements which may contain newlines
>_ set foo beta alpha\engamma
>_ set foo (string join0 $foo | sort \-z | string split0)
>_ string escape $foo[1]
alpha\engamma
.EE
.UNINDENT
.UNINDENT
.SH COPYRIGHT
fish-shell developers
.\" Generated by docutils manpage writer.
.