reference/strings/functions/strspn.xml
422bb032237525aaf50e6a43f33362a2c610a1d7
...
...
@@ -1,22 +1,34 @@
1
-
<?xml version="1.0" encoding="iso-8859-1"?>
1
+
<?xml version="1.0" encoding="utf-8"?>
2
2
<!-- $Revision$ -->
3
-
<refentry xmlns="http://docbook.org/ns/docbook" xml:id="function.strspn">
3
+
<refentry xml:id="function.strspn" xmlns="http://docbook.org/ns/docbook">
4
4
<refnamediv>
5
5
<refname>strspn</refname>
6
-
<refpurpose>Find length of initial segment matching mask</refpurpose>
6
+
<refpurpose>
7
+
Finds the length of the initial segment of a string consisting
8
+
entirely of characters contained within a given mask
9
+
</refpurpose>
7
10
</refnamediv>
8
11
9
12
<refsect1 role="description">
10
13
&reftitle.description;
11
14
<methodsynopsis>
12
15
<type>int</type><methodname>strspn</methodname>
13
-
<methodparam><type>string</type><parameter>str1</parameter></methodparam>
14
-
<methodparam><type>string</type><parameter>str2</parameter></methodparam>
15
-
<methodparam choice="opt"><type>int</type><parameter>start</parameter></methodparam>
16
-
<methodparam choice="opt"><type>int</type><parameter>length</parameter></methodparam>
16
+
<methodparam><type>string</type><parameter>string</parameter></methodparam>
17
+
<methodparam><type>string</type><parameter>characters</parameter></methodparam>
18
+
<methodparam choice="opt"><type>int</type><parameter>offset</parameter><initializer>0</initializer></methodparam>
19
+
<methodparam choice="opt"><type class="union"><type>int</type><type>null</type></type><parameter>length</parameter><initializer>&null;</initializer></methodparam>
17
20
</methodsynopsis>
18
21
<para>
19
-
Finds the length of the initial segment matching mask.
22
+
Finds the length of the initial segment of <parameter>string</parameter>
23
+
that contains <emphasis>only</emphasis> characters from <parameter>characters</parameter>.
24
+
</para>
25
+
<para>
26
+
If <parameter>offset</parameter> and <parameter>length</parameter>
27
+
are omitted, then all of <parameter>string</parameter> will be
28
+
examined. If they are included, then the effect will be the same as
29
+
calling <literal>strspn(substr($string, $offset, $length),
30
+
$characters)</literal> (see <xref linkend="function.substr"/>
31
+
for more information).
20
32
</para>
21
33
<para>
22
34
The line of code:
...
...
@@ -24,13 +36,15 @@
24
36
<programlisting role="php">
25
37
<![CDATA[
26
38
<?php
27
-
$var = strspn("42 is the answer, what is the question ...", "1234567890");
39
+
$var = strspn("42 is the answer to the 128th question.", "1234567890");
28
40
?>
29
41
]]>
30
42
</programlisting>
31
43
</informalexample>
32
-
will assign 2 to <varname>$var</varname>, because the string "42" will
33
-
be the longest segment containing characters from "1234567890".
44
+
will assign <literal>2</literal> to <varname>$var</varname>,
45
+
because the string "42" is the initial segment
46
+
of <parameter>string</parameter> that consists only of characters
47
+
contained within "1234567890".
34
48
</para>
35
49
</refsect1>
36
50

...
...
@@ -39,27 +53,44 @@ $var = strspn("42 is the answer, what is the question ...", "1234567890");
39
53
<para>
40
54
<variablelist>
41
55
<varlistentry>
42
-
<term><parameter>str1</parameter></term>
56
+
<term><parameter>string</parameter></term>
43
57
<listitem>
44
58
<para>
45
-
The first string.
59
+
The string to examine.
46
60
</para>
47
61
</listitem>
48
62
</varlistentry>
49
63
<varlistentry>
50
-
<term><parameter>str2</parameter></term>
64
+
<term><parameter>characters</parameter></term>
51
65
<listitem>
52
66
<para>
53
-
The second string.
67
+
The list of allowable characters.
54
68
</para>
55
69
</listitem>
56
70
</varlistentry>
57
71
<varlistentry>
58
-
<term><parameter>start</parameter></term>
72
+
<term><parameter>offset</parameter></term>
59
73
<listitem>
60
74
<para>
61
-
The start position of the string to examine.
62
-
Negative value counts position from the end of a string.
75
+
The position in <parameter>string</parameter> to
76
+
start searching.
77
+
</para>
78
+
<para>
79
+
If <parameter>offset</parameter> is given and is non-negative,
80
+
then <function>strspn</function> will begin
81
+
examining <parameter>string</parameter> at
82
+
the <parameter>offset</parameter>'th position. For instance, in
83
+
the string '<literal>abcdef</literal>', the character at
84
+
position <literal>0</literal> is '<literal>a</literal>', the
85
+
character at position <literal>2</literal> is
86
+
'<literal>c</literal>', and so forth.
87
+
</para>
88
+
<para>
89
+
If <parameter>offset</parameter> is given and is negative,
90
+
then <function>strspn</function> will begin
91
+
examining <parameter>string</parameter> at
92
+
the <parameter>offset</parameter>'th position from the end
93
+
of <parameter>string</parameter>.
63
94
</para>
64
95
</listitem>
65
96
</varlistentry>
...
...
@@ -67,8 +98,20 @@ $var = strspn("42 is the answer, what is the question ...", "1234567890");
67
98
<term><parameter>length</parameter></term>
68
99
<listitem>
69
100
<para>
70
-
The length of the string to examine.
71
-
Negative value sets length from the end of a string.
101
+
The length of the segment from <parameter>string</parameter>
102
+
to examine.
103
+
</para>
104
+
<para>
105
+
If <parameter>length</parameter> is given and is non-negative,
106
+
then <parameter>string</parameter> will be examined
107
+
for <parameter>length</parameter> characters after the starting
108
+
position.
109
+
</para>
110
+
<para>
111
+
If <parameter>length</parameter> is given and is negative,
112
+
then <parameter>string</parameter> will be examined from the
113
+
starting position up to <parameter>length</parameter>
114
+
characters from the end of <parameter>string</parameter>.
72
115
</para>
73
116
</listitem>
74
117
</varlistentry>
...
...
@@ -79,34 +122,38 @@ $var = strspn("42 is the answer, what is the question ...", "1234567890");
79
122
<refsect1 role="returnvalues">
80
123
&reftitle.returnvalues;
81
124
<para>
82
-
Returns the length of the initial segment of <parameter>str1</parameter>
83
-
which consists entirely of characters in <parameter>str2</parameter>.
125
+
Returns the length of the initial segment of <parameter>string</parameter>
126
+
which consists entirely of characters in <parameter>characters</parameter>.
84
127
</para>
128
+
<note>
129
+
<para>
130
+
When a <parameter>offset</parameter> parameter is set, the returned length
131
+
is counted starting from this position, not from the beginning of
132
+
<parameter>string</parameter>.
133
+
</para>
134
+
</note>
85
135
</refsect1>
86
136

87
137
<refsect1 role="changelog">
88
138
&reftitle.changelog;
89
-
<para>
90
-
<informaltable>
91
-
<tgroup cols="2">
92
-
<thead>
93
-
<row>
94
-
<entry>&Version;</entry>
95
-
<entry>&Description;</entry>
96
-
</row>
97
-
</thead>
98
-
<tbody>
99
-
<row>
100
-
<entry>4.3.0</entry>
101
-
<entry>
102
-
The <parameter>start</parameter> and <parameter>length</parameter>
103
-
parameters were added
104
-
</entry>
105
-
</row>
106
-
</tbody>
107
-
</tgroup>
108
-
</informaltable>
109
-
</para>
139
+
<informaltable>
140
+
<tgroup cols="2">
141
+
<thead>
142
+
<row>
143
+
<entry>&Version;</entry>
144
+
<entry>&Description;</entry>
145
+
</row>
146
+
</thead>
147
+
<tbody>
148
+
<row>
149
+
<entry>8.0.0</entry>
150
+
<entry>
151
+
<parameter>length</parameter> is nullable now.
152
+
</entry>
153
+
</row>
154
+
</tbody>
155
+
</tgroup>
156
+
</informaltable>
110
157
</refsect1>
111
158

112
159
<refsect1 role="examples">
...
...
@@ -117,10 +164,25 @@ $var = strspn("42 is the answer, what is the question ...", "1234567890");
117
164
<programlisting role="php">
118
165
<![CDATA[
119
166
<?php
120
-
echo strspn("foo", "o", 1, 2); // 2
167
+
// subject does not start with any characters from mask
168
+
var_dump(strspn("foo", "o"));
169
+

170
+
// examine two characters from subject starting at offset 1
171
+
var_dump(strspn("foo", "o", 1, 2));
172
+

173
+
// examine one character from subject starting at offset 1
174
+
var_dump(strspn("foo", "o", 1, 1));
121
175
?>
122
176
]]>
123
177
</programlisting>
178
+
&example.outputs;
179
+
<screen>
180
+
<![CDATA[
181
+
int(0)
182
+
int(2)
183
+
int(1)
184
+
]]>
185
+
</screen>
124
186
</example>
125
187
</para>
126
188
</refsect1>
...
...
@@ -140,7 +202,6 @@ echo strspn("foo", "o", 1, 2); // 2
140
202
</refsect1>
141
203

142
204
</refentry>
143
-

144
205
<!-- Keep this comment at the end of the file
145
206
Local variables:
146
207
mode: sgml
...
...
@@ -152,7 +213,7 @@ sgml-indent-step:1
152
213
sgml-indent-data:t
153
214
indent-tabs-mode:nil
154
215
sgml-parent-document:nil
155
-
sgml-default-dtd-file:"../../../../manual.ced"
216
+
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
156
217
sgml-exposed-tags:nil
157
218
sgml-local-catalogs:nil
158
219
sgml-local-ecat-files:nil
159
220