archived-doc-es/reference/strings/functions/strpos.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4b72b23513caa3a8bc520d459a0417defc7b3880 Maintainer: PhilDaiguille Status: ready -->
<!-- Reviewed: no Maintainer: Marqitos -->
<refentry xml:id="function.strpos" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>strpos</refname>
  <refpurpose>Busca la posición de la primera ocurrencia en un string</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>strpos</methodname>
   <methodparam><type>string</type><parameter>haystack</parameter></methodparam>
   <methodparam><type>string</type><parameter>needle</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Busca la posición numérica de la primera ocurrencia de
   <parameter>needle</parameter> en el &string;
   <parameter>haystack</parameter>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>haystack</parameter></term>
     <listitem>
      <para>
       El string en el que se debe buscar.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>needle</parameter></term>
     <listitem>
      <para>
       El string a buscar.
      </para>
      &strings.parameter.needle.non-string;
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       Si se especifica, la búsqueda comenzará a partir de este
       número de caracteres contados desde el inicio del string.
       Si este número es negativo, la búsqueda comenzará utilizando
       este número de caracteres pero comenzando desde el final del string.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Devuelve la posición numérica de la ocurrencia en relación
   con el inicio del string <parameter>haystack</parameter>
   (independientemente del <parameter>offset</parameter>).
   Nótese también que la posición en el string comienza
   en <literal>0</literal>, y no en <literal>1</literal>.
  </para>
  <para>
   Devuelve &false; si la ocurrencia no ha sido encontrada.
  </para>
  &return.falseproblem;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <itemizedlist>
   <listitem>
    <simpara>
     Si <parameter>offset</parameter> es mayor que la longitud de
     <parameter>haystack</parameter>, se lanzará un
     <classname>ValueError</classname>.
    </simpara>
   </listitem>
  </itemizedlist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <informaltable>
   <tgroup cols="2">
    <thead>
     <row>
      <entry>&Version;</entry>
      <entry>&Description;</entry>
     </row>
    </thead>
    <tbody>
     &strings.changelog.needle-empty;
     <row>
      <entry>8.0.0</entry>
      <entry>
       Pasar un &integer; como <parameter>needle</parameter> ya no está soportado.
      </entry>
     </row>
     <row>
      <entry>7.3.0</entry>
      <entry>
       Pasar un &integer; como <parameter>before_needle</parameter> ha sido
       declarado obsoleto.
      </entry>
     </row>
     <row>
      <entry>7.1.0</entry>
      <entry>
       Se ha añadido soporte para números negativos en el parámetro <parameter>offset</parameter>.
      </entry>
     </row>
    </tbody>
   </tgroup>
  </informaltable>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Con <literal>===</literal></title>
    <programlisting role="php">
<![CDATA[
<?php
$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).
if ($pos === false) {
    echo "El string '$findme' no se encuentra en el string '$mystring'";
} else {
    echo "El string '$findme' ha sido encontrado en el string '$mystring'";
    echo " y comienza en la posición $pos";
}
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Con !==</title>
    <programlisting role="php">
<![CDATA[
<?php
$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).
if ($pos !== false) {
    echo "El string '$findme' ha sido encontrado en el string '$mystring'";
    echo " y comienza en la posición $pos";
} else {
    echo "El string '$findme' no se encuentra en el string '$mystring'";
}
?>
]]>
    </programlisting>
   </example>

   <example>
    <title>Utilizar un offset</title>
    <programlisting role="php">
<![CDATA[
<?php
// Podemos buscar el carácter, e ignorar todo lo que está antes del offset
$newstring = 'abcdef abcdef';
$pos = strpos($newstring, 'a', 1); // $pos = 7, no 0
echo $pos, PHP_EOL;
?>
]]>
    </programlisting>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  &note.bin-safe;
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>stripos</function></member>
    <member><function>str_contains</function></member>
    <member><function>str_ends_with</function></member>
    <member><function>str_starts_with</function></member>
    <member><function>strrpos</function></member>
    <member><function>strripos</function></member>
    <member><function>strstr</function></member>
    <member><function>strpbrk</function></member>
    <member><function>substr</function></member>
    <member><function>preg_match</function></member>
   </simplelist>
  </para>
 </refsect1>

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->