[doc-en] master: Clarify that mb_strpos returns a character position, not a byte position (#5853)

Author: Louis-Arnaud (lacatoire) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-10T16:36:23+02:00 Commit: https://github.com/php/doc-en/commit/97f8edc4efed4d8ab86c56f200a36aefb37fdf24 Raw diff: https://github.com/php/doc-en/commit/97f8edc4efed4d8ab86c56f200a36aefb37fdf24.diff 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 Changed paths: M reference/mbstring/functions/mb-strpos.xml Diff: diff --git a/reference/mbstring/functions/mb-strpos.xml b/reference/mbstring/functions/mb-strpos.xml index 21f72bb86fbd..6768dd894359 100644 --- a/reference/mbstring/functions/mb-strpos.xml +++ b/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>