Adds note about grouping to split iterators.

lib/pure/strutils.nim

@@ -165,45 +165,50 @@ proc toOctal*(c: char): string {.noSideEffect, rtl, extern: "nsuToOctal".} =
     result[i] = Chr(val mod 8 + ord('0'))
     val = val div 8
 
-iterator split*(s: string, seps: set[char] = Whitespace): string =
+iterator split*(s: string, seps: set[char] = Whitespace): string =
-  ## Splits the string `s` into substrings.
+  ## Splits the string `s` into substrings using a group of separators.
-  ##
+  ##
-  ## Substrings are separated by a substring containing only `seps`.
+  ## Substrings are separated by a substring containing only `seps`. Note
-  ## Examples:
+  ## that whole sequences of characters found in ``seps`` will be counted as
-  ##
+  ## a single split point and leading/trailing separators will be ignored.
-  ## .. code-block:: nimrod
+  ## The following example:
-  ##   for word in split("  this is an  example  "):
+  ##
-  ##     writeln(stdout, word)
+  ## .. code-block:: nimrod
-  ##
+  ##   for word in split("  this is an  example  "):
-  ## Results in:
+  ##     writeln(stdout, word)
-  ##
+  ##
-  ## .. code-block:: nimrod
+  ## ...generates this output:
-  ##   "this"
+  ##
-  ##   "is"
+  ## .. code-block::
-  ##   "an"
+  ##   "this"
-  ##   "example"
+  ##   "is"
-  ##
+  ##   "an"
-  ##   for word in split(";;this;is;an;;example;;;", {';'}):
+  ##   "example"
-  ##     writeln(stdout, word)
+  ##
-  ##
+  ## And the following code:
-  ## produces the same output. The code:
+  ##
-  ##
+  ## .. code-block:: nimrod
-  ## .. code-block:: nimrod
+  ##   for word in split(";;this;is;an;;example;;;", {';'}):
-  ##   let date = "2012-11-20T22:08:08.398990"
+  ##     writeln(stdout, word)
-  ##   let separators = {' ', '-', ':', 'T'}
+  ##
-  ##   for number in split(date, separators):
+  ## ...produces the same output as the first example. The code:
-  ##     writeln(stdout, number)
+  ##
-  ##
+  ## .. code-block:: nimrod
-  ## Results in:
+  ##   let date = "2012-11-20T22:08:08.398990"
-  ##
+  ##   let separators = {' ', '-', ':', 'T'}
-  ## .. code-block:: nimrod
+  ##   for number in split(date, separators):
-  ##   "2012"
+  ##     writeln(stdout, number)
-  ##   "11"
+  ##
-  ##   "20"
+  ## ...results in:
-  ##   "22"
+  ##
-  ##   "08"
+  ## .. code-block::
-  ##   "08.398990"
+  ##   "2012"
-  ##
+  ##   "11"
+  ##   "20"
+  ##   "22"
+  ##   "08"
+  ##   "08.398990"
+  ##
   var last = 0
   assert(not ('\0' in seps))
   while last < len(s):
@@ -214,10 +219,12 @@ iterator split*(s: string, seps: set[char] = Whitespace): string =
       yield substr(s, first, last-1)
 
 iterator split*(s: string, sep: char): string =
-  ## Splits the string `s` into substrings.
+  ## Splits the string `s` into substrings using a single separator.
   ##
   ## Substrings are separated by the character `sep`.
-  ## Example:
+  ## Unlike the version of the iterator which accepts a set of separator
+  ## characters, this proc will not coalesce groups of the
+  ## separator, returning a string for each found character. The code:
   ##
   ## .. code-block:: nimrod
   ##   for word in split(";;this;is;an;;example;;;", ';'):
@@ -225,7 +232,7 @@ iterator split*(s: string, sep: char): string =
   ##
   ## Results in:
   ##
-  ## .. code-block:: nimrod
+  ## .. code-block::
   ##   ""
   ##   ""
   ##   "this"