preg-split.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: bb66ce4d449049730d4967ce74fb68f15a138612 Maintainer: samesch Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.preg-split" xmlns="http://docbook.org/ns/docbook">
 <refnamediv>
  <refname>preg_split</refname>
  <refpurpose>Zerlegt eine Zeichenkette anhand eines regulären Ausdrucks</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type class="union"><type>array</type><type>false</type></type><methodname>preg_split</methodname>
   <methodparam><type>string</type><parameter>pattern</parameter></methodparam>
   <methodparam><type>string</type><parameter>subject</parameter></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>limit</parameter><initializer>-1</initializer></methodparam>
   <methodparam choice="opt"><type>int</type><parameter>flags</parameter><initializer>0</initializer></methodparam>
  </methodsynopsis>
  <para>
   Zerlegt die angegebene Zeichenkette anhand eines regulären Ausdrucks.
  </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 zerlegende Zeichenkette.
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>limit</parameter></term>
     <listitem>
      <para>
       Falls angegeben, werden maximal <parameter>limit</parameter>
       Teilzeichenketten zurückgegeben, wobei der Rest der Zeichenkette in der
       letzten Teilzeichenkette abgelegt wird. Ein
       <parameter>limit</parameter> von -1 oder 0 bedeutet "kein Limit".
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>flags</parameter></term>
     <listitem>
      <para>
       <parameter>flags</parameter> kann jede Kombination der folgenden Flags
       sein (verknüpft mit dem bitweisen <literal>|</literal> Operator):
       <variablelist>
        <varlistentry>
         <term><constant>PREG_SPLIT_NO_EMPTY</constant></term>
         <listitem>
          <simpara>
           Falls dieses Flag gesetzt ist, werden von
           <function>preg_split</function> nur die Teile zurückgegeben, die
           nicht leer sind.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>PREG_SPLIT_DELIM_CAPTURE</constant></term>
         <listitem>
          <simpara>
           Falls dieses Flag gesetzt ist, werden auch die eingeklammerten
           Ausdrücke des Trennsymbol-Suchmusters erfasst und zurückgegeben.
          </simpara>
         </listitem>
        </varlistentry>
        <varlistentry>
         <term><constant>PREG_SPLIT_OFFSET_CAPTURE</constant></term>
         <listitem>
          <para>
           Falls dieses Flag gesetzt ist, wird mit jeder gefundenen
           Übereinstimmung die dazugehörige Position in der Zeichenkette
           zurückgegeben. Zu beachten ist, dass dies die Rückgabewerte in
           einem Array dahingehend ändert, dass 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.
          </para>
         </listitem>
        </varlistentry>
       </variablelist>
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>

 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   Gibt ein Array zurück, bestehend aus Teilzeichenketten der Zeichenkette
   <parameter>subject</parameter>, die an den auf das Suchmuster
   <parameter>pattern</parameter> passenden Stellen zerlegt wurde.
   &return.falseforfailure;
  </para>
 </refsect1>

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

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>preg_split</function>-Beispiel: Eine Zeichenkette in Teile zerlegen</title>
    <programlisting role="php">
<![CDATA[
<?php
// zerlegt die Zeichenkette an Stellen mit beliebiger Anzahl von
// Kommata oder Leerzeichen, die " ", \r, \t, \n und \f umfassen
$schluesselwoerter = preg_split("/[\s,]+/", "hypertext language, programming");
print_r($schluesselwoerter);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => hypertext
    [1] => language
    [2] => programming
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Eine Zeichenkette in einzelne Zeichen zerlegen</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'string';
$zeichen = preg_split('//', $str, -1, PREG_SPLIT_NO_EMPTY);
print_r($zeichen);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => s
    [1] => t
    [2] => r
    [3] => i
    [4] => n
    [5] => g
)
]]>
    </screen>
   </example>
  </para>
  <para>
   <example>
    <title>Zerlegen einer Zeichenkette in Suchtreffer und Erfassen der Positionen</title>
    <programlisting role="php">
<![CDATA[
<?php
$str = 'hypertext language programming';
$zeichen = preg_split('/ /', $str, -1, PREG_SPLIT_OFFSET_CAPTURE);
print_r($zeichen);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
Array
(
    [0] => Array
        (
            [0] => hypertext
            [1] => 0
        )

    [1] => Array
        (
            [0] => language
            [1] => 10
        )

    [2] => Array
        (
            [0] => programming
            [1] => 19
        )

)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  <tip>
   <para>
    Falls die Leistungsfähigkeit regulärer Ausdrücke nicht benötigt wird,
    können stattdessen schnellere (und gleichzeitig einfachere) Alternativen
    wie <function>explode</function> oder <function>str_split</function>
    verwendet werden.
   </para>
  </tip>
  <tip>
   <para>
    Falls keine Übereinstimmungen gefunden wurden, wird ein Array mit nur
    einem Element zurückgegeben, das die übergebene Zeichenkette enthält.
   </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>explode</function></member>
    <member><function>preg_match</function></member>
    <member><function>preg_match_all</function></member>
    <member><function>preg_replace</function></member>
    <member><function>preg_last_error</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
-->