Clarify that mb_strpos returns a character position, not a byte position (#5853)

* Clarify mb_strpos returns character position, not byte; add example

* Clarify offset parameter is in characters

Author: lacatoire

reference/mbstring/functions/mb-strpos.xml

@@ -52,10 +52,10 @@
     <varlistentry>
      <term><parameter>offset</parameter></term>
      <listitem>
-      <para>
-       The search offset. If it is not specified, 0 is used.
+      <simpara>
+       The search offset in characters. If it is not specified, 0 is used.
        A negative offset counts from the end of the string.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -70,12 +70,12 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Returns the numeric position of
-   the first occurrence of <parameter>needle</parameter> in the
-   <parameter>haystack</parameter> <type>string</type>. If
-   <parameter>needle</parameter> is not found, it returns &false;.
-  </para>
+  <simpara>
+   Returns the character position (not byte position) of the first occurrence
+   of <parameter>needle</parameter> in the <parameter>haystack</parameter>
+   <type>string</type>, counting from <literal>0</literal>.
+   Returns &false; if <parameter>needle</parameter> is not found.
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
@@ -115,10 +115,37 @@
   </informaltable>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>mb_strpos</function> returns a character offset, not a byte offset</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// "🐘" is 4 bytes but 1 character; "é" is 2 bytes but 1 character
+$str = "🐘H🐘é";
+
+var_dump(mb_strpos($str, "é"));  // character 3, not byte 9
+var_dump(mb_strpos($str, "🐘", 1)); // character 2, skipping the first "🐘"
+?>
+]]>
+   </programlisting>
+   &example.outputs;
+   <screen>
+<![CDATA[
+int(3)
+int(2)
+]]>
+   </screen>
+  </example>
+ </refsect1>
+
  <refsect1 role="seealso">
   &reftitle.seealso;
   <para>
    <simplelist>
+    <member><function>mb_strrpos</function></member>
+    <member><function>mb_stripos</function></member>
     <member><function>mb_internal_encoding</function></member>
     <member><function>strpos</function></member>
    </simplelist>