From 45cbabb3158184e81570fc1ccc87d07406026612 Mon Sep 17 00:00:00 2001
From: Torben Wilson <torben@php.net>
Date: Sun, 10 Sep 2000 22:46:43 +0000
Subject: [PATCH] Added another example to preg_split() and a pointer to it
 from split(), addressing what seems to be a common request in the notes from
 people coming from perl.

git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@32418 c90b9560-bf6c-de11-be94-00142212c4b1
---
 functions/pcre.xml  | 35 +++++++++++++++++++++++++++--------
 functions/regex.xml | 11 +++++++++++
 2 files changed, 38 insertions(+), 8 deletions(-)

diff --git a/functions/pcre.xml b/functions/pcre.xml
index 6e0052c3f7..95c39dd01f 100644
--- a/functions/pcre.xml
+++ b/functions/pcre.xml
@@ -457,37 +457,56 @@ $text = preg_replace ($search, $replace, $document);
       </paramdef>
      </funcprototype>
     </funcsynopsis>
+
     <note>
      <para>
       Parameter <parameter>flags</parameter> was added in PHP 4 Beta 3.
      </para>
     </note>
+
     <para>
      Returns an array containing substrings of
      <parameter>subject</parameter> split along boundaries matched by
      <parameter>pattern</parameter>.
     </para>
+
     <para>
      If <parameter>limit</parameter> is specified, then only substrings
      up to <parameter>limit</parameter> are returned.
     </para>
+
     <para>
-     If flags is PREG_SPLIT_NO_EMPTY then only non-empty pieces will
-     be by <function>preg_split</function>.
+     If flags is <constant>PREG_SPLIT_NO_EMPTY</constant> then only
+     non-empty pieces will be by <function>preg_split</function>.
     </para>
-    <para>
-     <example>
-      <title>Getting parts of search string</title>
-      <programlisting role="php">
+
+    <example>
+     <title><function>preg_split</function> example</title>
+     <para>
+      Get the parts of a search string.
+     </para>
+     <programlisting role="php">
 // split the phrase by any number of commas or space characters,
 // which include " ", \r, \t, \n and \f
 $keywords = preg_split ("/[\s,]+/", "hypertext language, programming");
-      </programlisting>
-     </example>
+     </programlisting>
+
+     <para>
+      Splitting a string into component characters.
+     </para>
+     <programlisting role="php">
+$str = 'string';
+$chars = preg_split('//', $str, 0, PREG_SPLIT_NO_EMPTY);
+print_r($chars);
+     </programlisting>
+    </example>
+
+    <para>
      See also <function>preg_match</function>,
      <function>preg_match_all</function>, and
      <function>preg_replace</function>.
     </para>
+
    </refsect1>
   </refentry>
 
diff --git a/functions/regex.xml b/functions/regex.xml
index d83712b61c..abf989347a 100644
--- a/functions/regex.xml
+++ b/functions/regex.xml
@@ -335,14 +335,23 @@ echo "Month: $month; Day: $day; Year: $year&lt;br&gt;\n";
       </programlisting>
      </example>
     </para>
+
     <para>
      Note that <parameter>pattern</parameter> is case-sensitive.
     </para>
+
     <para>
      Note that if you don't require the power of regular expressions,
      it is faster to use <function>explode</function>, which doesn't
      incur the overhead of the regular expression engine.
     </para>
+
+    <para>
+     For users looking for a way to emulate perl's <command>$chars =
+      split('', $str)</command> behaviour, please see the examples for
+     <function>preg_split</function>.
+    </para>
+
     <para>
      Please note that <parameter>pattern</parameter> is a regular
      expression.  If you want to split on any of the characters which
@@ -355,10 +364,12 @@ echo "Month: $month; Day: $day; Year: $year&lt;br&gt;\n";
      something along the lines of <command>man
      /usr/local/src/regex/regex.7</command> in order to read it.
     </para>
+
     <para>
      See also: <function>spliti</function>,
      <function>explode</function>, and <function>implode</function>.
     </para>
+
    </refsect1>
   </refentry>