Skip to content

Commit 9947012

Browse files
jordikroonkamil-tekielalacatoire
authored
sscanf/fscanf: Clarify negative -1 return value(#5580)
* clarify fscanf/sscanf negative return value Co-authored-by: Kamil Tekiela <tekiela246@gmail.com> Co-authored-by: Louis-Arnaud <la.catoire@gmail.com>
1 parent 2d8dcd3 commit 9947012

3 files changed

Lines changed: 154 additions & 156 deletions

File tree

‎reference/filesystem/functions/fscanf.xml‎

Lines changed: 52 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -14,66 +14,68 @@
1414
<methodparam><type>string</type><parameter>format</parameter></methodparam>
1515
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
1616
</methodsynopsis>
17-
<para>
17+
<simpara>
1818
The function <function>fscanf</function> is similar to
1919
<function>sscanf</function>, but it takes its input from a file
2020
associated with <parameter>stream</parameter> and interprets the
2121
input according to the specified <parameter>format</parameter>.
22-
</para>
23-
<para>
22+
</simpara>
23+
<simpara>
2424
Any whitespace in the format string matches any whitespace in the input
2525
stream. This means that even a tab (<literal>\t</literal>) in the format
2626
string can match a single space character in the input stream.
27-
</para>
28-
<para>
27+
</simpara>
28+
<simpara>
2929
Each call to <function>fscanf</function> reads one line from the file.
30-
</para>
30+
</simpara>
3131
</refsect1>
3232

3333
<refsect1 role="parameters">
3434
&reftitle.parameters;
35-
<para>
36-
<variablelist>
37-
<varlistentry>
38-
<term><parameter>stream</parameter></term>
39-
<listitem>
40-
&fs.file.pointer;
41-
</listitem>
42-
</varlistentry>
43-
&strings.scanf.parameter.format;
44-
<varlistentry>
45-
<term><parameter>vars</parameter></term>
46-
<listitem>
47-
<para>
48-
The optional assigned values.
49-
</para>
50-
</listitem>
51-
</varlistentry>
52-
</variablelist>
53-
</para>
35+
<variablelist>
36+
<varlistentry>
37+
<term><parameter>stream</parameter></term>
38+
<listitem>
39+
&fs.file.pointer;
40+
</listitem>
41+
</varlistentry>
42+
&strings.scanf.parameter.format;
43+
<varlistentry>
44+
<term><parameter>vars</parameter></term>
45+
<listitem>
46+
<simpara>
47+
The optional assigned values.
48+
</simpara>
49+
</listitem>
50+
</varlistentry>
51+
</variablelist>
5452
</refsect1>
5553

5654
<refsect1 role="returnvalues">
5755
&reftitle.returnvalues;
58-
<para>
56+
<simpara>
5957
If only two parameters were passed to this function, the values parsed will be
60-
returned as an array. Otherwise, if optional parameters are passed, the
61-
function will return the number of assigned values. The optional
58+
returned as an <type>array</type>. Otherwise, if optional parameters are passed,
59+
the function will return the number of assigned values. The optional
6260
parameters must be passed by reference.
63-
</para>
64-
<para>
61+
</simpara>
62+
<simpara>
6563
If there are more substrings expected in the <parameter>format</parameter>
6664
than there are available within <parameter>string</parameter>,
6765
&null; will be returned. On other errors, &false; will be returned.
68-
</para>
66+
</simpara>
67+
<simpara>
68+
When optional parameters are used and the end of the input read from
69+
<parameter>stream</parameter> is reached before any value has been
70+
parsed, <literal>-1</literal> is returned.
71+
</simpara>
6972
</refsect1>
7073

7174
<refsect1 role="examples">
7275
&reftitle.examples;
73-
<para>
74-
<example>
75-
<title><function>fscanf</function> Example</title>
76-
<programlisting role="php">
76+
<example>
77+
<title><function>fscanf</function> Example</title>
78+
<programlisting role="php">
7779
<![CDATA[
7880
<?php
7981
$handle = fopen("users.txt", "r");
@@ -84,36 +86,31 @@ while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
8486
fclose($handle);
8587
?>
8688
]]>
87-
</programlisting>
88-
</example>
89-
</para>
90-
<para>
91-
<example>
92-
<title>Contents of users.txt</title>
93-
<programlisting role="txt">
89+
</programlisting>
90+
</example>
91+
<example>
92+
<title>Contents of users.txt</title>
93+
<programlisting role="txt">
9494
<![CDATA[
9595
javier argonaut pe
9696
hiroshi sculptor jp
9797
robert slacker us
9898
luigi florist it
9999
]]>
100-
</programlisting>
101-
</example>
102-
</para>
100+
</programlisting>
101+
</example>
103102
</refsect1>
104103

105104
<refsect1 role="seealso">
106105
&reftitle.seealso;
107-
<para>
108-
<simplelist>
109-
<member><function>fread</function></member>
110-
<member><function>fgets</function></member>
111-
<member><function>fgetss</function></member>
112-
<member><function>sscanf</function></member>
113-
<member><function>printf</function></member>
114-
<member><function>sprintf</function></member>
115-
</simplelist>
116-
</para>
106+
<simplelist>
107+
<member><function>fread</function></member>
108+
<member><function>fgets</function></member>
109+
<member><function>fgetss</function></member>
110+
<member><function>sscanf</function></member>
111+
<member><function>printf</function></member>
112+
<member><function>sprintf</function></member>
113+
</simplelist>
117114
</refsect1>
118115

119116
</refentry>

‎reference/spl/splfileobject/fscanf.xml‎

Lines changed: 45 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -13,81 +13,85 @@
1313
<methodparam><type>string</type><parameter>format</parameter></methodparam>
1414
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
1515
</methodsynopsis>
16-
<para>
16+
<simpara>
1717
Reads a line from the file and interprets it according to the specified <parameter>format</parameter>.
18-
</para>
19-
<para>
18+
</simpara>
19+
<simpara>
2020
Any whitespace in the <parameter>format</parameter> string matches any whitespace in the line from the file.
2121
This means that even a tab (<literal>\t</literal>) in the format string can match a single space character in the input stream.
22-
</para>
22+
</simpara>
2323
</refsect1>
2424

2525
<refsect1 role="parameters">
2626
&reftitle.parameters;
27-
<para>
28-
<variablelist>
29-
&strings.scanf.parameter.format;
30-
<varlistentry>
31-
<term><parameter>vars</parameter></term>
32-
<listitem>
33-
<para>
34-
The optional assigned values.
35-
</para>
36-
</listitem>
37-
</varlistentry>
38-
</variablelist>
39-
</para>
27+
<variablelist>
28+
&strings.scanf.parameter.format;
29+
<varlistentry>
30+
<term><parameter>vars</parameter></term>
31+
<listitem>
32+
<simpara>
33+
The optional assigned values.
34+
</simpara>
35+
</listitem>
36+
</varlistentry>
37+
</variablelist>
4038
</refsect1>
4139

4240
<refsect1 role="returnvalues">
4341
&reftitle.returnvalues;
44-
<para>
42+
<simpara>
4543
If only one parameter is passed to this method, the values parsed will be
46-
returned as an array. Otherwise, if optional parameters are passed, the
47-
function will return the number of assigned values. The optional
44+
returned as an <type>array</type>. Otherwise, if optional parameters are passed,
45+
the method will return the number of assigned values. The optional
4846
parameters must be passed by reference.
49-
</para>
47+
</simpara>
48+
<simpara>
49+
If there are more substrings expected in the <parameter>format</parameter>
50+
than there are available in the line read from the file,
51+
&null; will be returned.
52+
</simpara>
53+
<simpara>
54+
When optional parameters are used and the end of the line read from the
55+
file is reached before any value has been parsed, <literal>-1</literal>
56+
is returned.
57+
</simpara>
5058
</refsect1>
5159

5260
<refsect1 role="examples">
5361
&reftitle.examples;
54-
<para>
55-
<example>
56-
<title><methodname>SplFileObject::fscanf</methodname> example</title>
57-
<programlisting role="php">
62+
<example>
63+
<title><methodname>SplFileObject::fscanf</methodname> example</title>
64+
<programlisting role="php">
5865
<![CDATA[
5966
<?php
6067
$file = new SplFileObject("misc.txt");
6168
while ($userinfo = $file->fscanf("%s %s %s")) {
62-
list ($name, $profession, $countrycode) = $userinfo;
63-
// Do something with $name $profession $countrycode
69+
list ($name, $profession, $countrycode) = $userinfo;
70+
// Do something with $name $profession $countrycode
6471
}
6572
?>
6673
]]>
67-
</programlisting>
68-
<para>Contents of users.txt</para>
69-
<programlisting role="txt">
74+
</programlisting>
75+
<simpara>Contents of users.txt</simpara>
76+
<programlisting role="txt">
7077
<![CDATA[
7178
javier argonaut pe
7279
hiroshi sculptor jp
7380
robert slacker us
7481
luigi florist it
7582
]]>
76-
</programlisting>
77-
</example>
78-
</para>
83+
</programlisting>
84+
</example>
7985
</refsect1>
8086

8187
<refsect1 role="seealso">
8288
&reftitle.seealso;
83-
<para>
84-
<simplelist>
85-
<member><function>fscanf</function></member>
86-
<member><function>sscanf</function></member>
87-
<member><function>printf</function></member>
88-
<member><function>sprintf</function></member>
89-
</simplelist>
90-
</para>
89+
<simplelist>
90+
<member><function>fscanf</function></member>
91+
<member><function>sscanf</function></member>
92+
<member><function>printf</function></member>
93+
<member><function>sprintf</function></member>
94+
</simplelist>
9195
</refsect1>
9296

9397
</refentry>

0 commit comments

Comments
 (0)