[PHP-DOC] strlen and multi-byte characters

[Adam Kazimierczak]

Hello Mailing List,

I found that strlen is often considered as a function that counts 
characters in strings, rather than bytes. Such mistake is even often 
seen on blogs or tutorials, so many PHP beginners may get confused when 
they try to strlen a multi-byte characters string.

I am attaching a patch proposition where the description notes that 
length is measured in bytes and adds an example showing results of 
strlen used on multi-byte character strings.

Please let me know what do you think about this.

Cheers,
Adam
Index: en/reference/strings/functions/strlen.xml
===================================================================
--- en/reference/strings/functions/strlen.xml	(revision 330489)
+++ en/reference/strings/functions/strlen.xml	(working copy)
@@ -13,7 +13,7 @@
    <methodparam><type>string</type><parameter>string</parameter></methodparam>
   </methodsynopsis>
   <para>
-   Returns the length of the given <parameter>string</parameter>.
+   Returns the length of the given <parameter>string</parameter> measured in bytes.
   </para>
  </refsect1>
 
@@ -81,6 +81,26 @@
 ]]>
     </programlisting>
    </example>
+   <example>
+    <title>A <function>strlen</function> example using multi-byte characters</title>
+    <programlisting role="php">
+<![CDATA[
+<?php
+$str = 'ab'; // Using one-byte characters
+echo strlen($str); // 2
+
+$str = 'äå'; // Using two-byte characters
+echo strlen($str); // 4
+
+$str = '恶妇'; // Using three-byte characters
+echo strlen($str); // 6
+
+$str = 'aä猫'; // Using various byte length characters
+echo strlen($str); // 6 = 1+2+3
+?>
+]]>
+    </programlisting>
+   </example>
   </para>
  </refsect1>