Skip to content

[Sync EN] sscanf/fscanf: Clarify negative -1 return value (#5580) #2952

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

Merged
lacatoire merged 1 commit into from
May 31, 2026
+164 −169
Merged

[Sync EN] sscanf/fscanf: Clarify negative -1 return value (#5580) #2952

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
114 changes: 55 additions & 59 deletions reference/filesystem/functions/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: 4225e50bc391ddba99e367c231463da0dc04357d Maintainer: yannick Status: ready -->
<!-- EN-Revision: 9947012f745f0fb6e083bce5a8c920213ff468b7 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="function.fscanf" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
Expand All @@ -16,67 +15,69 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
La fonction <function>fscanf</function> est similaire à la fonction
<function>sscanf</function>, sauf qu'elle prend un fichier en entrée,
représenté par la ressource <parameter>stream</parameter> et interprète
l'entrée en fonction du format <parameter>format</parameter> spécifié.
</para>
<para>
Tous les caractères blancs de la chaîne de formatage correspondent
</simpara>
<simpara>
Tous les caractères blancs de la chaîne de formatage correspondent
à autant d'espaces dans le flux d'entrée. Cela signifie qu'une tabulation
(<literal>\t</literal>) dans la chaîne de format peut remplacer
(<literal>\t</literal>) dans la chaîne de format peut remplacer
un espace simple dans le flux d'entrée.
</para>
<para>
</simpara>
<simpara>
Chaque appel à la fonction <function>fscanf</function> lit une ligne du fichier.
</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>
Les valeurs optionnelles à assigner.
</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>
Les valeurs optionnelles à assigner.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Si seulement 2 paramètres sont passés à la fonction, la valeur analysée
sera retournée sous la forme d'un tableau. Si des paramètres optionnels
sont passés, la fonction retourne le nombre de valeurs assignées.
sera retournée sous la forme d'un <type>array</type>. Si des paramètres
optionnels sont passés, la fonction retourne le nombre de valeurs assignées.
Les paramètres optionnels doivent être passés par référence.
</para>
<para>
</simpara>
<simpara>
S'il y a plus de sous-chaînes attendues dans le <parameter>format</parameter>
que disponibles dans <parameter>string</parameter>,
&null; sera retourné. Pour les autres erreurs, &false; sera retourné.
</para>
</simpara>
<simpara>
Lorsque des paramètres optionnels sont utilisés et que la fin de l'entrée
lue depuis <parameter>stream</parameter> est atteinte avant qu'aucune
valeur n'ait été analysée, <literal>-1</literal> est retourné.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Exemple avec <function>fscanf</function></title>
<programlisting role="php">
<example>
<title>Exemple avec <function>fscanf</function></title>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("users.txt", "r");
Expand All @@ -87,36 +88,31 @@ while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
fclose($handle);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Contenu du fichier users.txt</title>
<programlisting role="txt">
</programlisting>
</example>
<example>
<title>Contenu du fichier users.txt</title>
<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>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
92 changes: 48 additions & 44 deletions reference/spl/splfileobject/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->
<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: jpauli Status: ready -->
<!-- EN-Revision: 9947012f745f0fb6e083bce5a8c920213ff468b7 Maintainer: lacatoire Status: ready -->
<!-- Reviewed: no -->
<refentry xml:id="splfileobject.fscanf" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
<refnamediv>
Expand All @@ -15,84 +14,89 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Lit une ligne depuis un fichier et l'analyse suivant le format
<parameter>format</parameter> spécifié.
</para>
<para>
</simpara>
<simpara>
Les espaces blancs dans la chaîne <parameter>format</parameter> correspondent
aux espaces blancs dans la ligne du fichier.
Ceci signifie qu'une tabulation (<literal>\t</literal>) dans le format
va correspondre à un seul caractère blanc dans le flux d'entrée.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<para>
Les valeurs optionnelles assignées.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<simpara>
Les valeurs optionnelles assignées.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Si seul 1 paramètre est passé à cette méthode, la valeur analysée
sera retournée sous la forme d'un tableau. Sinon, si les paramètres optionnelles
sont passés, la fonction retourne le nombre de valeurs assignées.
Les paramètres optionnels doivent être passés par référence.
</para>
sera retournée sous la forme d'un <type>array</type>. Sinon, si des
paramètres optionnels sont passés, la méthode retourne le nombre de
valeurs assignées. Les paramètres optionnels doivent être passés par
référence.
</simpara>
<simpara>
S'il y a plus de sous-chaînes attendues dans le <parameter>format</parameter>
que disponibles dans la ligne lue depuis le fichier,
&null; sera retourné.
</simpara>
<simpara>
Lorsque des paramètres optionnels sont utilisés et que la fin de la ligne
lue depuis le fichier est atteinte avant qu'aucune valeur n'ait été
analysée, <literal>-1</literal> est retourné.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Exemple avec <methodname>SplFileObject::fscanf</methodname></title>
<programlisting role="php">
<example>
<title>Exemple avec <methodname>SplFileObject::fscanf</methodname></title>
<programlisting role="php">
<![CDATA[
<?php
$file = new SplFileObject("misc.txt");
while ($userinfo = $file->fscanf("%s %s %s")) {
list ($name, $profession, $countrycode) = $userinfo;
// Faire des opérations sur $name $profession $countrycode
list ($name, $profession, $countrycode) = $userinfo;
// Faire des opérations sur $name $profession $countrycode
}
?>
]]>
</programlisting>
<para>Contenu de users.txt</para>
<programlisting role="txt">
</programlisting>
<simpara>Contenu de 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
Loading