Skip to content

Clarify negative -1 return value for sscanf/fscanf #5580

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jordikroon wants to merge 7 commits into
base: master
Choose a base branch
from
+154 −156
Open

Clarify negative -1 return value for sscanf/fscanf #5580

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
44bd943
change style of sscanf
jordikroon May 24, 2026
3ce71f8
change style of fscanf and mark array as type
jordikroon May 24, 2026
7af7c98
clarify fscanf/sscanf negative return value
jordikroon May 24, 2026
0515da6
convert para to simpara
jordikroon May 24, 2026
435b30e
Remove indent from CDATA
jordikroon May 25, 2026
3c76dab
Apply suggestions from code review
jordikroon May 25, 2026
16be287
Apply suggestions from code review
jordikroon May 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
111 changes: 54 additions & 57 deletions reference/filesystem/functions/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,67 +14,69 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
The function <function>fscanf</function> is similar to
<function>sscanf</function>, but it takes its input from a file
associated with <parameter>stream</parameter> and interprets the
input according to the specified <parameter>format</parameter>.
</para>
<para>
</simpara>
<simpara>
Any whitespace in the format string matches any whitespace in the input
stream. This means that even a tab (<literal>\t</literal>) in the format
string can match a single space character in the input stream.
</para>
<para>
</simpara>
<simpara>
Each call to <function>fscanf</function> reads one line from the file.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
<varlistentry>
<term><parameter>stream</parameter></term>
<listitem>
&fs.file.pointer;
</listitem>
</varlistentry>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<para>
The optional assigned values.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
<varlistentry>
<term><parameter>stream</parameter></term>
<listitem>
&fs.file.pointer;
</listitem>
</varlistentry>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<simpara>
The optional assigned values.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
If only two parameters were passed to this function, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
returned as an <type>array</type>. Otherwise, if optional parameters are passed,
the function will return the number of assigned values. The optional
parameters must be passed by reference.
</para>
<para>
</simpara>
<simpara>
If there are more substrings expected in the <parameter>format</parameter>
than there are available within <parameter>string</parameter>,
&null; will be returned. On other errors, &false; will be returned.
</para>
</simpara>
<simpara>
When optional parameters are used and the end of the input
<parameter>string</parameter> is reached before any value has been
parsed, <literal>-1</literal> is returned.
Comment thread
jordikroon marked this conversation as resolved.
Outdated
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>fscanf</function> Example</title>
<programlisting role="php">
<![CDATA[
<example>
<title><function>fscanf</function> Example</title>
<programlisting role="php">
<![CDATA[
Comment thread
jordikroon marked this conversation as resolved.
Outdated
<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
Expand All @@ -84,36 +86,31 @@ while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
fclose($handle);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Contents of users.txt</title>
<programlisting role="txt">
<![CDATA[
</programlisting>
</example>
<example>
<title>Contents of users.txt</title>
<programlisting role="txt">
<![CDATA[
Comment thread
jordikroon marked this conversation as resolved.
Outdated
javier argonaut pe
hiroshi sculptor jp
robert slacker us
luigi florist it
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>fread</function></member>
<member><function>fgets</function></member>
<member><function>fgetss</function></member>
<member><function>sscanf</function></member>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
</simplelist>
</para>
<simplelist>
<member><function>fread</function></member>
<member><function>fgets</function></member>
<member><function>fgetss</function></member>
<member><function>sscanf</function></member>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
88 changes: 46 additions & 42 deletions reference/spl/splfileobject/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,81 +13,85 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Reads a line from the file and interprets it according to the specified <parameter>format</parameter>.
</para>
<para>
</simpara>
<simpara>
Any whitespace in the <parameter>format</parameter> string matches any whitespace in the line from the file.
This means that even a tab (<literal>\t</literal>) in the format string can match a single space character in the input stream.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<para>
The optional assigned values.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<simpara>
The optional assigned values.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
If only one parameter is passed to this method, the values parsed will be
returned as an array. Otherwise, if optional parameters are passed, the
function will return the number of assigned values. The optional
<simpara>
If only two parameters were passed to this function, the values parsed will be
returned as an <type>array</type>. Otherwise, if optional parameters are passed,
the function will return the number of assigned values. The optional
parameters must be passed by reference.
Comment thread
jordikroon marked this conversation as resolved.
Outdated
</para>
</simpara>
<simpara>
If there are more substrings expected in the <parameter>format</parameter>
than there are available within <parameter>string</parameter>,
Comment thread
jordikroon marked this conversation as resolved.
Outdated
&null; will be returned. On other errors, &false; will be returned.
Comment thread
jordikroon marked this conversation as resolved.
Outdated
</simpara>
<simpara>
When optional parameters are used and the end of the input
<parameter>string</parameter> is reached before any value has been
parsed, <literal>-1</literal> is returned.
Comment thread
jordikroon marked this conversation as resolved.
Outdated
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><methodname>SplFileObject::fscanf</methodname> example</title>
<programlisting role="php">
<example>
<title><methodname>SplFileObject::fscanf</methodname> example</title>
<programlisting role="php">
<![CDATA[
<?php
$file = new SplFileObject("misc.txt");
while ($userinfo = $file->fscanf("%s %s %s")) {
list ($name, $profession, $countrycode) = $userinfo;
// Do something with $name $profession $countrycode
list ($name, $profession, $countrycode) = $userinfo;
// Do something with $name $profession $countrycode
}
?>
]]>
</programlisting>
<para>Contents of users.txt</para>
<programlisting role="txt">
</programlisting>
<simpara>Contents of users.txt</simpara>
<programlisting role="txt">
<![CDATA[
javier argonaut pe
hiroshi sculptor jp
robert slacker us
luigi florist it
]]>
</programlisting>
</example>
</para>
</programlisting>
</example>
</refsect1>

<refsect1 role="seealso">
&reftitle.seealso;
<para>
<simplelist>
<member><function>fscanf</function></member>
<member><function>sscanf</function></member>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
</simplelist>
</para>
<simplelist>
<member><function>fscanf</function></member>
<member><function>sscanf</function></member>
<member><function>printf</function></member>
<member><function>sprintf</function></member>
</simplelist>
</refsect1>

</refentry>
Expand Down
Loading