Add examples for Re.split function (#216)

* Add examples for Re.split function

Adds a few examples of using zero-length patterns as inputs to Re.split.  Examples are taken from the test suite.  Related to #119 and #120.

* Clarify zero-length pattern split behavior

* Add examples for Re.split_delim function

Adds a few examples of using zero-length patterns as inputs to Re.split_delim.  Examples are taken from the test suite.  Related to #119 and #120.

lib/core.mli

@@ -303,6 +303,35 @@ val matches_seq : ?pos:int -> ?len:int -> re -> string -> string Seq.t
 
       # Re.split ~pos:3 regex "1,2,3,4. Commas go brrr.";;
       - : string list = ["3"; "4. Commas go brrr."]
+    ]}
+
+    {6 Zero-length patterns:}
+
+    Be careful when using [split] with zero-length patterns like [eol], [bow],
+    and [eow].  Because they don't have any width, they will still be present in
+    the result. (Note the position of the [\n] and space characters in the
+    output.)
+
+    {[
+      # Re.split (Re.compile Re.eol) "a\nb";;
+      - : string list = ["a"; "\nb"]
+
+      # Re.split (Re.compile Re.bow) "a b";;
+      - : string list = ["a "; "b"]
+
+      # Re.split (Re.compile Re.eow) "a b";;
+      - : string list = ["a"; " b"]
+    ]}
+
+    Compare this to the behavior of splitting on the char itself. (Note that
+    the delimiters are not present in the output.)
+
+    {[
+      # Re.split (Re.compile (Re.char '\n')) "a\nb";;
+      - : string list = ["a"; "b"]
+
+      # Re.split (Re.compile (Re.char ' ')) "a b";;
+      - : string list = ["a"; "b"]
     ]} *)
 val split : ?pos:int -> ?len:int -> re -> string -> string list
 
@@ -327,6 +356,35 @@ val split : ?pos:int -> ?len:int -> re -> string -> string list
 
       # Re.split ~pos:3 regex "1,2,3,4. Commas go brrr.";;
       - : string list = ["3"; "4. Commas go brrr."]
+    ]}
+
+    {6 Zero-length patterns:}
+
+    Be careful when using [split_delim] with zero-length patterns like [eol],
+    [bow], and [eow].  Because they don't have any width, they will still be
+    present in the result. (Note the position of the [\n] and space characters
+    in the output.)
+
+    {[
+      # Re.split_delim (Re.compile Re.eol) "a\nb";;
+      - : string list = ["a"; "\nb"; ""]
+
+      # Re.split_delim (Re.compile Re.bow) "a b";;
+      - : string list = [""; "a "; "b"]
+
+      # Re.split_delim (Re.compile Re.eow) "a b";;
+      - : string list = ["a"; " b"; ""]
+    ]}
+
+    Compare this to the behavior of splitting on the char itself. (Note that
+    the delimiters are not present in the output.)
+
+    {[
+      # Re.split_delim (Re.compile (Re.char '\n')) "a\nb";;
+      - : string list = ["a"; "b"]
+
+      # Re.split_delim (Re.compile (Re.char ' ')) "a b";;
+      - : string list = ["a"; "b"]
     ]} *)
 val split_delim : ?pos:int -> ?len:int -> re -> string -> string list