Skip to content

[Sync-En] strpos, mb_strpos: document the empty needle and character positions #1317

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
julionc merged 1 commit into from
Sep 18, 2026
+52 −18
Merged

[Sync-En] strpos, mb_strpos: document the empty needle and character positions #1317

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
49 changes: 38 additions & 11 deletions reference/mbstring/functions/mb-strpos.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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">
Expand Down Expand Up @@ -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>
Expand All @@ -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">
Expand Down Expand Up @@ -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>
Expand Down
21 changes: 14 additions & 7 deletions reference/strings/functions/strpos.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand All @@ -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'";
Expand All @@ -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";
Expand Down