From 362a553ce66019e6a9d122b98f68a1aba7fdec74 Mon Sep 17 00:00:00 2001
From: Louis-Arnaud <la.catoire@gmail.com>
Date: Tue, 15 Sep 2026 09:29:02 +0200
Subject: [PATCH] [Sync-En] strpos, mb_strpos: document the empty needle and
 character positions

---
 reference/mbstring/functions/mb-strpos.xml | 49 +++++++++++++++++-----
 reference/strings/functions/strpos.xml     | 21 ++++++----
 2 files changed, 52 insertions(+), 18 deletions(-)

diff --git a/reference/mbstring/functions/mb-strpos.xml b/reference/mbstring/functions/mb-strpos.xml
index eea2afa8c7..1d4c60b3c6 100644
--- a/reference/mbstring/functions/mb-strpos.xml
+++ b/reference/mbstring/functions/mb-strpos.xml
@@ -1,11 +1,11 @@
 <?xml version="1.0" encoding="utf-8"?>
 <!-- $Revision$ -->
-<!-- EN-Revision: 95d05546430b9e5db225dd42a0d285b870f0da42 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: 97f8edc4efed4d8ab86c56f200a36aefb37fdf24 Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no Maintainer: Marqitos -->
 <refentry xml:id="function.mb-strpos" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <refnamediv>
   <refname>mb_strpos</refname>
-  <refpurpose>Localiza la primera ocurrencia de un carácter en una cadena</refpurpose>
+  <refpurpose>Busca la posición de la primera ocurrencia de un string en otro string</refpurpose>
  </refnamediv>
 
  <refsect1 role="description">
@@ -56,10 +56,10 @@
     <varlistentry>
      <term><parameter>offset</parameter></term>
      <listitem>
-      <para>
-       La posición de inicio de la búsqueda. Si se omite, se utilizará cero.
+      <simpara>
+       La posición de inicio de la búsqueda, en caracteres. Si se omite, se utilizará cero.
        Una posición negativa se cuenta desde el final de la &string;.
-      </para>
+      </simpara>
      </listitem>
     </varlistentry>
     <varlistentry>
@@ -74,12 +74,12 @@
 
  <refsect1 role="returnvalues">
   &reftitle.returnvalues;
-  <para>
-   Devuelve la posición numérica de
-   la primera ocurrencia del carácter <parameter>needle</parameter> en la
-   cadena <parameter>haystack</parameter>. Si <parameter>needle</parameter> no se
-   encuentra, <function>mb_strpos</function> devuelve &false;.
-  </para>
+  <simpara>
+   Devuelve la posición en caracteres (no en bytes) de la primera ocurrencia
+   de <parameter>needle</parameter> en el <type>string</type>
+   <parameter>haystack</parameter>, contando desde <literal>0</literal>.
+   Devuelve &false; si no se encuentra <parameter>needle</parameter>.
+  </simpara>
  </refsect1>
 
  <refsect1 role="errors">
@@ -119,10 +119,37 @@
   </informaltable>
  </refsect1>
 
+ <refsect1 role="examples">
+  &reftitle.examples;
+  <example>
+   <title><function>mb_strpos</function> devuelve una posición en caracteres, no en bytes</title>
+   <programlisting role="php">
+<![CDATA[
+<?php
+// "🐘" ocupa 4 bytes pero es 1 carácter; "é" ocupa 2 bytes pero es 1 carácter
+$str = "🐘H🐘é";
+
+var_dump(mb_strpos($str, "é"));  // carácter 3, no byte 9
+var_dump(mb_strpos($str, "🐘", 1)); // carácter 2, se omite el primer "🐘"
+?>
+]]>
+   </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>
diff --git a/reference/strings/functions/strpos.xml b/reference/strings/functions/strpos.xml
index 498332e5a7..984e3efade 100644
--- a/reference/strings/functions/strpos.xml
+++ b/reference/strings/functions/strpos.xml
@@ -1,5 +1,5 @@
 <?xml version="1.0" encoding="utf-8"?>
-<!-- EN-Revision: 4b72b23513caa3a8bc520d459a0417defc7b3880 Maintainer: PhilDaiguille Status: ready -->
+<!-- EN-Revision: dd5db7c6b22c45108b19ca815a0bdf07909bf14a Maintainer: PhilDaiguille Status: ready -->
 <!-- Reviewed: no Maintainer: Marqitos -->
 <refentry xml:id="function.strpos" xmlns="http://docbook.org/ns/docbook">
  <refnamediv>
@@ -37,9 +37,15 @@
     <varlistentry>
      <term><parameter>needle</parameter></term>
      <listitem>
-      <para>
+      <simpara>
        El string a buscar.
-      </para>
+      </simpara>
+      <simpara>
+       Pasar un string vacío como <parameter>needle</parameter> coincide en
+       todas las posiciones. <function>strpos</function> devuelve
+       <parameter>offset</parameter> si se especifica, o
+       <literal>0</literal> en caso contrario.
+      </simpara>
       &strings.parameter.needle.non-string;
      </listitem>
     </varlistentry>
@@ -107,7 +113,7 @@
      <row>
       <entry>7.3.0</entry>
       <entry>
-       Pasar un &integer; como <parameter>before_needle</parameter> ha sido
+       Pasar un &integer; como <parameter>needle</parameter> ha sido
        declarado obsoleto.
       </entry>
      </row>
@@ -134,7 +140,7 @@ $mystring = 'abc';
 $findme   = 'a';
 $pos = strpos($mystring, $findme);
 
-// Note nuestra utilización de ===.  == no funcionaría como esperado
+// Note nuestra utilización de ===.  == no funcionaría como se esperaba
 // ya que la posición de 'a' es el carácter 0 (primero).
 if ($pos === false) {
     echo "El string '$findme' no se encuentra en el string '$mystring'";
@@ -156,8 +162,9 @@ $mystring = 'abc';
 $findme   = 'a';
 $pos = strpos($mystring, $findme);
 
-// Note nuestra utilización de !==.  != no funcionaría como esperado
-// ya que la posición de 'a' es el carácter 0 (primero).
+// También se puede utilizar el operador !==.  != no funcionaría como se esperaba
+// ya que la posición de 'a' es 0. La expresión (0 != false) se evalúa
+// como false.
 if ($pos !== false) {
     echo "El string '$findme' ha sido encontrado en el string '$mystring'";
     echo " y comienza en la posición $pos";