php-doc-en/reference/strings/functions/strtok.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strtok" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>strtok</refname>
  <refpurpose>Tokenize string</refpurpose>
 </refnamediv>
 
 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <type>string</type><methodname>strtok</methodname>
   <methodparam><type>string</type><parameter>str</parameter></methodparam>
   <methodparam><type>string</type><parameter>token</parameter></methodparam>
  </methodsynopsis>
  <methodsynopsis>
   <type>string</type><methodname>strtok</methodname>
   <methodparam><type>string</type><parameter>token</parameter></methodparam>
  </methodsynopsis>
  <para>
   <function>strtok</function> splits a string (<parameter>str</parameter>)
   into smaller strings (tokens), with each token being delimited by any
   character from <parameter>token</parameter>.
   That is, if you have a string like "This is an example string" you
   could tokenize this string into its individual words by using the
   space character as the token.
  </para>
  <para>
   Note that only the first call to strtok uses the string argument.
   Every subsequent call to strtok only needs the token to use, as
   it keeps track of where it is in the current string.  To start
   over, or to tokenize a new string you simply call strtok with the
   string argument again to initialize it.  Note that you may put
   multiple tokens in the token parameter.  The string will be
   tokenized when any one of the characters in the argument are
   found.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <para>
   <variablelist>
    <varlistentry>
     <term><parameter>str</parameter></term>
     <listitem>
      <para>
       The <type>string</type> being split up into smaller strings (tokens).
      </para>
     </listitem>
    </varlistentry>
    <varlistentry>
     <term><parameter>token</parameter></term>
     <listitem>
      <para>
       The delimiter used when splitting up <parameter>str</parameter>.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </para>
 </refsect1>
 
 <refsect1 role="returnvalues">
  &reftitle.returnvalues;
  <para>
   A <type>string</type> token.
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <para>
   <example>
    <title><function>strtok</function> example</title>
    <programlisting role="php">
<![CDATA[
<?php
$string = "This is\tan example\nstring";
/* Use tab and newline as tokenizing characters as well  */
$tok = strtok($string, " \n\t");

while ($tok !== false) {
    echo "Word=$tok<br />";
    $tok = strtok(" \n\t");
}
?>
]]>
    </programlisting>
   </example>
  </para> 
  <para>
   The behavior when an empty part was found changed with PHP 4.1.0. The old
   behavior returned an empty string, while the new, correct, behavior
   simply skips the part of the string:
  </para>
  <para>
   <example>
    <title>Old <function>strtok</function> behavior</title>
    <programlisting role="php">
<![CDATA[
<?php
$first_token  = strtok('/something', '/');
$second_token = strtok('/');
var_dump($first_token, $second_token);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
    string(0) ""
    string(9) "something"
]]>
    </screen>
   </example>
   <example>
    <title>New <function>strtok</function> behavior</title>
    <programlisting role="php">
<![CDATA[
<?php
$first_token  = strtok('/something', '/');
$second_token = strtok('/');
var_dump($first_token, $second_token);
?>
]]>
    </programlisting>
    &example.outputs;
    <screen>
<![CDATA[
    string(9) "something"
    bool(false)
]]>
    </screen>
   </example>
  </para>
 </refsect1>

 <refsect1 role="notes">
  &reftitle.notes;
  
  &return.falseproblem;
 </refsect1>
 
 <refsect1 role="seealso">
  &reftitle.seealso;
  <para>
   <simplelist>
    <member><function>split</function></member>
    <member><function>explode</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
-->