reference/strings/functions/strtok.xml
443d81b33e6537a000cc235c2a11748ba8d56232
443d81b33e6537a000cc235c2a11748ba8d56232
...
...
@@ -1,6 +1,6 @@
1
1
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strtok" xmlns:xlink="http://www.w3.org/1999/xlink">
3
+
<refentry xml:id="function.strtok" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
4
4
<refnamediv>
5
5
<refname>strtok</refname>
6
6
<refpurpose>Tokenize string</refpurpose>
...
...
@@ -9,32 +9,49 @@
9
9
<refsect1 role="description">
10
10
&reftitle.description;
11
11
<methodsynopsis>
12
-
<type>string</type><methodname>strtok</methodname>
13
-
<methodparam><type>string</type><parameter>str</parameter></methodparam>
12
+
<type class="union"><type>string</type><type>false</type></type><methodname>strtok</methodname>
13
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
14
14
<methodparam><type>string</type><parameter>token</parameter></methodparam>
15
15
</methodsynopsis>
16
+
<simpara>Alternative signature (not supported with named arguments):</simpara>
16
17
<methodsynopsis>
17
-
<type>string</type><methodname>strtok</methodname>
18
+
<type class="union"><type>string</type><type>false</type></type><methodname>strtok</methodname>
18
19
<methodparam><type>string</type><parameter>token</parameter></methodparam>
19
20
</methodsynopsis>
20
21
<para>
21
-
<function>strtok</function> splits a string (<parameter>str</parameter>)
22
+
<function>strtok</function> splits a string (<parameter>string</parameter>)
22
23
into smaller strings (tokens), with each token being delimited by any
23
24
character from <parameter>token</parameter>.
24
25
That is, if you have a string like "This is an example string" you
25
26
could tokenize this string into its individual words by using the
26
-
space character as the token.
27
+
space character as the <parameter>token</parameter>.
27
28
</para>
28
29
<para>
29
-
Note that only the first call to strtok uses the string argument.
30
-
Every subsequent call to strtok only needs the token to use, as
30
+
Note that only the first call to strtok uses the <parameter>string</parameter> argument.
31
+
Every subsequent call to strtok only needs the <parameter>token</parameter> to use, as
31
32
it keeps track of where it is in the current string. To start
32
33
over, or to tokenize a new string you simply call strtok with the
33
-
string argument again to initialize it. Note that you may put
34
-
multiple tokens in the token parameter. The string will be
35
-
tokenized when any one of the characters in the argument are
34
+
<parameter>string</parameter> argument again to initialize it. Note that you may put
35
+
multiple tokens in the <parameter>token</parameter> parameter. The string will be
36
+
tokenized when any one of the characters in the <parameter>token</parameter> argument is
36
37
found.
37
38
</para>
39
+
<note>
40
+
<para>
41
+
This function behaves slightly different from what one may expect being
42
+
familiar with <function>explode</function>.
43
+
First, a sequence of two or more contiguous <parameter>token</parameter>
44
+
characters in the parsed string is considered to be a single delimiter.
45
+
Also, a <parameter>token</parameter> situated at the start or end of the
46
+
string is ignored.
47
+
For example, if a string <literal>";aaa;;bbb;"</literal> is used, successive
48
+
calls to <function>strtok</function> with <literal>";"</literal> as a
49
+
<parameter>token</parameter> would return strings
50
+
"aaa" and "bbb", and then &false;.
51
+
As a result, the string will be split into only two elements, while
52
+
<literal>explode(";", $string)</literal> would return an array of 5 elements.
53
+
</para>
54
+
</note>
38
55
</refsect1>
39
56
40
57
<refsect1 role="parameters">
...
...
@@ -42,7 +59,7 @@
42
59
<para>
43
60
<variablelist>
44
61
<varlistentry>
45
-
<term><parameter>str</parameter></term>
62
+
<term><parameter>string</parameter></term>
46
63
<listitem>
47
64
<para>
48
65
The <type>string</type> being split up into smaller strings (tokens).
...
...
@@ -53,7 +70,7 @@
53
70
<term><parameter>token</parameter></term>
54
71
<listitem>
55
72
<para>
56
-
The delimiter used when splitting up <parameter>str</parameter>.
73
+
The delimiter used when splitting up <parameter>string</parameter>.
57
74
</para>
58
75
</listitem>
59
76
</varlistentry>
...
...
@@ -64,7 +81,31 @@
64
81
<refsect1 role="returnvalues">
65
82
&reftitle.returnvalues;
66
83
<para>
67
-
A <type>string</type> token.
84
+
A <type>string</type> token, or &false; if no more tokens are available.
85
+
</para>
86
+
</refsect1>
87
+
88
+
<refsect1 role="changelog">
89
+
&reftitle.changelog;
90
+
<para>
91
+
<informaltable>
92
+
<tgroup cols="2">
93
+
<thead>
94
+
<row>
95
+
<entry>&Version;</entry>
96
+
<entry>&Description;</entry>
97
+
</row>
98
+
</thead>
99
+
<tbody>
100
+
<row>
101
+
<entry>8.3.0</entry>
102
+
<entry>
103
+
Now emits <constant>E_WARNING</constant> when <parameter>token</parameter> is not provided.
104
+
</entry>
105
+
</row>
106
+
</tbody>
107
+
</tgroup>
108
+
</informaltable>
68
109
</para>
69
110
</refsect1>
70
111
...
...
@@ -90,13 +131,8 @@ while ($tok !== false) {
90
131
</example>
91
132
</para>
92
133
<para>
93
-
The behavior when an empty part was found changed with PHP 4.1.0. The old
94
-
behavior returned an empty string, while the new, correct, behavior
95
-
simply skips the part of the string:
96
-
</para>
97
-
<para>
98
134
<example>
99
-
<title>Old <function>strtok</function> behavior</title>
135
+
<title><function>strtok</function> behavior on empty part found</title>
100
136
<programlisting role="php">
101
137
<![CDATA[
102
138
<?php
...
...
@@ -109,27 +145,37 @@ var_dump($first_token, $second_token);
109
145
&example.outputs;
110
146
<screen>
111
147
<![CDATA[
112
-
string(0) ""
113
148
string(9) "something"
149
+
bool(false)
114
150
]]>
115
151
</screen>
116
152
</example>
153
+
</para>
154
+
<para>
117
155
<example>
118
-
<title>New <function>strtok</function> behavior</title>
156
+
<title>The difference between <function>strtok</function> and <function>explode</function></title>
119
157
<programlisting role="php">
120
158
<![CDATA[
121
159
<?php
122
-
$first_token = strtok('/something', '/');
123
-
$second_token = strtok('/');
124
-
var_dump($first_token, $second_token);
125
-
?>
160
+
$string = ";aaa;;bbb;";
161
+
162
+
$parts = [];
163
+
$tok = strtok($string, ";");
164
+
while ($tok !== false) {
165
+
$parts[] = $tok;
166
+
$tok = strtok(";");
167
+
}
168
+
echo json_encode($parts),"\n";
169
+
170
+
$parts = explode(";", $string);
171
+
echo json_encode($parts),"\n";
126
172
]]>
127
173
</programlisting>
128
174
&example.outputs;
129
175
<screen>
130
176
<![CDATA[
131
-
string(9) "something"
132
-
bool(false)
177
+
["aaa","bbb"]
178
+
["","aaa","","bbb",""]
133
179
]]>
134
180
</screen>
135
181
</example>
...
...
@@ -146,14 +192,12 @@ var_dump($first_token, $second_token);
146
192
&reftitle.seealso;
147
193
<para>
148
194
<simplelist>
149
-
<member><function>split</function></member>
150
195
<member><function>explode</function></member>
151
196
</simplelist>
152
197
</para>
153
198
</refsect1>
154
199
155
200
</refentry>
156
-
157
201
<!-- Keep this comment at the end of the file
158
202
Local variables:
159
203
mode: sgml
160
204