String::Split() documentation and test

[libacl.git] / doc / string.xml

diff --git a/doc/string.xml b/doc/string.xml
index 998bfcd..e4ceabc 100644 (file)
--- a/doc/string.xml
+++ b/doc/string.xml
@@ -217,7 +217,7 @@ Convert the string to all lower-case characters.
 </section>
 
 <section>
-<heading>Pattern matching</heading>
+<heading>Searching in Strings</heading>
 <description>
 <item tag="int in(String &amp;x)">
 Find the string x within the string. Returns the index where <emph>x</emph> was
@@ -225,6 +225,32 @@ found. Returns -1 if x was not found in the string. see also strstr().
 </item>
 </description>
 </section>
+
+<section>
+<heading>Splitting Strings into SuperStrings</heading>
+<description>
+<item tag="SuperString split(String &amp;separator)">
+Return a list of the words in the string, using <emph>separator</emph> as the delimiter string.
+<example>
+String numbers(&quot;2,4,7&quot;);
+numbers.split(",");  // &quot;2&quot; &quot;4&quot; &quot;7&quot;
+</example>
+Splitting an empty string will result in a SuperString with an empty string as its only element.
+The <emph>separator</emph> can be a multiple character string, for example:
+<example>
+String somexml(&quot;A&amp;amp;B&amp;amp;C&quot;);
+somexml.split("&amp;amp;");   // "A" "B" "C"
+</example>
+Consecutive separators are not grouped together and are deemed to delimit empty strings, for example:
+<example>
+String numbers(&quot;3.14   42&quot;);   //  Note 3 spaces
+numbers.split(" ");   // "3.14" "" ""  "42"
+</example>
+This also happens with separators at the start and the end of the string.
+</item>
+</description>
+</section>
+
 <section>
 <heading>Stream I/O</heading>
 <para>