preg-match.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d6f54016d62904cfd8200604aadd5e3f0d9bad97 Maintainer: samesch Status: ready -->
<!-- Reviewed: yes -->
<!-- Rev-Revision: 41c8533ff5a8f93ba9fdf0732d05dd5ab79864c9 Reviewer: samesch -->
<refentry xml:id="function.preg-match" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_match</refname>
  <refpurpose>Führt eine Suche mit einem regulären Ausdruck durch</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>int</type><type>false</type></type><methodname>preg_match</methodname>
   <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>array</type><parameter role="reference">matches</parameter><initializer>&null;</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Durchsucht <parameter>subject</parameter> nach Übereinstimmungen mit dem in
   <parameter>pattern</parameter> angegebenen regulären Ausdruck.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>pattern</parameter></term>
     <listitem>
      <para>
       Der Ausdruck, nach dem gesucht werden soll, als Zeichenkette.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>subject</parameter></term>
     <listitem>
      <para>
       Die zu durchsuchende Zeichenkette.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>matches</parameter></term>
     <listitem>
      <para>
       Falls der Parameter <parameter>matches</parameter> angegeben wurde,
       wird er mit den Suchergebnissen gefüllt. <varname>$matches[0]</varname>
       enthält dann den Text, der auf das komplette Suchmuster passt,
       <varname>$matches[1]</varname> den Text, der auf das erste
       eingeklammerte Teilsuchmuster passt und so weiter.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter> kann eine Kombination der folgenden Flags
       sein:
       <variablelist>
        <varlistentry>
         <term><constant>PREG_OFFSET_CAPTURE</constant></term>
         <listitem>
          <para>
           Wenn dieses Flag gesetzt ist, wird mit jeder gefundenen
           Übereinstimmung die dazugehörige Position in der Zeichenkette (in
           Bytes) zurückgegeben. Zu beachten ist, dass dies den Wert von
           <parameter>matches</parameter> in ein Array ändert, in dem jedes
           Element ein Array ist, das aus der übereinstimmenden Zeichenkette
           als Element <literal>0</literal> und deren Stelle in
           <parameter>subject</parameter> als Element <literal>1</literal>
           besteht.
           <informalexample>
            <programlisting role="php">
<![CDATA[
<?php
preg_match('/(foo)(bar)(baz)/', 'foobarbaz', $matches, PREG_OFFSET_CAPTURE);
print_r($matches);
?>
]]>
            </programlisting>
            &example.outputs;
            <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [0] => foobarbaz
            [1] => 0
        )

    [1] => Array
        (
            [0] => foo
            [1] => 0
        )

    [2] => Array
        (
            [0] => bar
            [1] => 3
        )

    [3] => Array
        (
            [0] => baz
            [1] => 6
        )

)
]]>
            </screen>
           </informalexample>
          </para>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>PREG_UNMATCHED_AS_NULL</constant></term>
         <listitem>
          <para>
           Wird dieses Flag angegeben, werden nicht gefundene Teilsuchmuster
           als &null; zurückgegeben; andernfalls werden sie als eine leere
           Zeichenkette (<type>&string;</type>) zurückgegeben.
           <informalexample>
            <programlisting role="php">
<![CDATA[
<?php
preg_match('/(a)(b)*(c)/', 'ac', $matches);
var_dump($matches);
preg_match('/(a)(b)*(c)/', 'ac', $matches, PREG_UNMATCHED_AS_NULL);
var_dump($matches);
?>
]]>
            </programlisting>
            &example.outputs;
            <screen>
<![CDATA[
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  string(0) ""
  [3]=>
  string(1) "c"
}
array(4) {
  [0]=>
  string(2) "ac"
  [1]=>
  string(1) "a"
  [2]=>
  NULL
  [3]=>
  string(1) "c"
}
]]>
            </screen>
           </informalexample>
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>offset</parameter></term>
     <listitem>
      <para>
       Normalerweise beginnt die Suche am Anfang der Zeichenkette. Der
       optionale Parameter <parameter>offset</parameter> kann verwendet
       werden, um eine andere Stelle in Bytes anzugeben, ab der gesucht werden
       soll.
      </para>
      <note>
       <para>
        Die Verwendung von <parameter>offset</parameter> entspricht nicht der
        Übergabe von <code>substr($subject, $offset)</code> an Stelle der
        Zeichenkette an <function>preg_match</function>, weil
        <parameter>pattern</parameter> Angaben wie <emphasis>^</emphasis>,
        <emphasis>$</emphasis> oder <emphasis>(?&lt;=x)</emphasis> enthalten
        kann. Vergleiche:
        <informalexample>
         <programlisting role="php">
<![CDATA[
<?php
$zeichenkette = "abcdef";
$suchmuster = '/^def/';
preg_match($suchmuster, $zeichenkette, $treffer, PREG_OFFSET_CAPTURE, 3);
print_r($treffer);
?>
]]>
         </programlisting>
         &example.outputs;
         <screen>
<![CDATA[
Array
(
)
]]>
         </screen>
         <para>
          während dieses Beispiel
         </para>
         <programlisting role="php">
<![CDATA[
<?php
$zeichenkette = "abcdef";
$suchmuster = '/^def/';
preg_match($suchmuster, substr($zeichenkette,3), $treffer, PREG_OFFSET_CAPTURE);
print_r($treffer);
?>
]]>
         </programlisting>
         <para>
          folgende Ausgabe erzeugt
         </para>
         <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [0] => def
            [1] => 0
        )
)
]]>
         </screen>
         <para>
          Als Alternative, um die Verwendung von <function>substr</function>
          zu vermeiden, kann die Assertion <literal>\G</literal> statt des
          Ankers <literal>^</literal> verwendet werden, oder stattdessen der
          Modifikator <literal>A</literal>; beide funktionieren in Kombination
          mit dem Parameter <parameter>offset</parameter>.
         </para>
        </informalexample>
       </para>
      </note>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   <function>preg_match</function> gibt 1 zurück, falls eine Übereinstimmung
   zwischen <parameter>pattern</parameter> und <parameter>subject</parameter>
   gefunden wurde, 0, falls nicht. &return.falseforfailure;
  </para>
  &return.falseproblem;
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  &pcre.pattern.warning;
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>7.2.0</entry>
       <entry>
        Beim Parameter <parameter>$flags</parameter> wird nun die Konstante
        <constant>PREG_UNMATCHED_AS_NULL</constant> unterstützt.
       </entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title>Die Zeichenkette "php" finden</title>
    <programlisting role="php">
<![CDATA[
<?php
// Das "i" nach der Suchmuster-Begrenzung kennzeichnet eine Suche ohne
// Berücksichtigung von Groß- und Kleinschreibung
if (preg_match("/php/i", "PHP ist die Web-Skriptsprache der Wahl.")) {
    echo "Es wurde eine Übereinstimmung gefunden.";
} else {
    echo "Es wurde keine Übereinstimmung gefunden.";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Die Zeichenkette "web" finden</title>
    <programlisting role="php">
<![CDATA[
<?php
// Das \b im Suchmuster kennzeichnet eine Wortgrenze, weshalb nur eine
// Übereinstimmung mit der einzelnen Zeichenkette "web" gefunden wird und
// nicht ein Teilwort in "webbing" oder "cobweb"
if (preg_match("/\bweb\b/i", "Für das Web ist PHP die Skriptsprache der Wahl.")) {
    echo "Es wurde eine Übereinstimmung gefunden.";
} else {
    echo "Es wurde keine Übereinstimmung gefunden.";
}

echo "\n";

if (preg_match("/\bweb\b/i", "PHP ist die Web-Skriptsprache der Wahl.")) {
    echo "Es wurde eine Übereinstimmung gefunden.";
} else {
    echo "Es wurde keine Übereinstimmung gefunden.";
}
?>
]]>
    </programlisting>
   </example>
  </para>
  <para>
   <example>
    <title>Den Domänen-Namen aus einer URL holen</title>
    <programlisting role="php">
<![CDATA[
<?php
// den Hostnamen aus URL holen
preg_match('@^(?:http://)?([^/]+)@i',
    "http://www.php.net/index.html", $treffer);
$host = $treffer[1];

// die letzten beiden Segmente aus Hostnamen holen
preg_match('/[^.]+\.[^.]+$/', $host, $treffer);
echo "Der Domänen-Name lautet: {$treffer[0]}\n";
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Der Domänen-Name lautet: php.net
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Benannte Teilsuchmuster (named subpatterns)</title>
    <programlisting role="php">
<![CDATA[
<?php

$str = 'foobar: 2008';

preg_match('/(?P<name>\w+): (?P<zahl>\d+)/', $str, $treffer);

/* Alternative */
// preg_match('/(?<name>\w+): (?<zahl>\d+)/', $str, $treffer);

print_r($treffer);

?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => foobar: 2008
    [name] => foobar
    [1] => foobar
    [zahl] => 2008
    [2] => 2008
)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <tip>
   <para>
    Verwenden Sie nicht <function>preg_match</function>, wenn Sie nur
    überprüfen wollen, ob eine Zeichenkette in einer anderen Zeichenkette
    enthalten ist. Verwenden Sie dafür stattdessen die Funktion
    <function>strpos</function>, die das schneller erledigt.
   </para>
  </tip>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><link linkend="pcre.pattern">PCRE-Suchmuster</link></member>
    <member><function>preg_quote</function></member>
    <member><function>preg_match_all</function></member>
    <member><function>preg_replace</function></member>
    <member><function>preg_split</function></member>
    <member><function>preg_last_error</function></member>
    <member><function>preg_last_error_msg</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
-->