From b1176323e715fe05fc24579cec15d721071c8419 Mon Sep 17 00:00:00 2001
From: ridiculousfish <corydoras@ridiculousfish.com>
Date: Sun, 24 Jun 2018 13:07:14 -0700
Subject: [PATCH] Document string split0

---
 doc_src/string.txt | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/doc_src/string.txt b/doc_src/string.txt
index 04b44884d..6d6b7c908 100644
--- a/doc_src/string.txt
+++ b/doc_src/string.txt
@@ -14,6 +14,8 @@ string replace [(-a | --all)] [(-f | --filter)] [(-i | --ignore-case)] [(-r | --
                [(-q | --quiet)] PATTERN REPLACEMENT [STRING...]
 string split [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)] SEP
              [STRING...]
+string split0 [(-m | --max) MAX] [(-n | --no-empty)] [(-q | --quiet)] [(-r | --right)]
+              [STRING...]
 string sub [(-s | --start) START] [(-l | --length) LENGTH] [(-q | --quiet)]
            [STRING...]
 string trim [(-l | --left)] [(-r | --right)] [(-c | --chars CHARS)]
@@ -93,6 +95,12 @@ Exit status: 0 if at least one replacement was performed, or 1 otherwise.
 
 See also `read --delimiter`.
 
+\subsection string-split0 "split0" subcommand
+
+`string split0` splits each STRING on the zero byte (NUL). Options are the same as `string split` except that no separator is given.
+
+`split0` 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 `find -print0` or `sort -z`. See split0 examples below.
+
 \subsection string-sub "sub" subcommand
 
 `string sub` prints a substring of each string argument. The start of the substring can be specified with `-s` or `--start` followed by a 1-based index value. Positive index values are relative to the start of the string and negative index values are relative to the end of the string. The default start value is 1. The length of the substring can be specified with `-l` or `--length`. If the length is not specified, the substring continues to the end of each STRING. Exit status: 0 if at least one substring operation was performed, 1 otherwise.
@@ -240,6 +248,13 @@ foo2
 <outp>0xBadC0de</outp>
 \endfish
 
+\subsection string-example-split0 Split0 Examples
+
+\fish{cli-dark}
+# Count files in a directory, without being confused by newlines.
+>_ count (find . -print0 | string split0)
+\endfish
+
 \subsection string-example-replace-literal Replace Literal Examples
 
 \fish{cli-dark}