Skip to content

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

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
julionc merged 1 commit into from
May 31, 2026
Merged

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

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
108 changes: 52 additions & 56 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: PhilDaiguille Status: ready -->
<!-- EN-Revision: 9947012f745f0fb6e083bce5a8c920213ff468b7 Maintainer: PhilDaiguille 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 función <function>fscanf</function> es similar a la función
<function>sscanf</function>, excepto que toma un archivo como entrada,
representado por el recurso <parameter>stream</parameter> e interpreta
la entrada según el formato <parameter>format</parameter> especificado.
</para>
<para>
</simpara>
<simpara>
Todos los caracteres en blanco de la cadena de formato corresponden
a tantos espacios en el flujo de entrada. Esto significa que una tabulación
(<literal>\t</literal>) en la cadena de formato puede reemplazar
un espacio simple en el flujo de entrada.
</para>
<para>
</simpara>
<simpara>
Cada llamada a la función <function>fscanf</function> lee una línea del archivo.
</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>
Los valores opcionales a asignar.
</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>
Los valores opcionales a asignar.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Si solo se pasan 2 argumentos a la función, el valor analizado
será devuelto en forma de un array. Si se pasan argumentos opcionales,
será devuelto como un <type>array</type>. Si se pasan argumentos opcionales,
la función devolverá el número de valores asignados.
Los argumentos opcionales deben ser pasados por referencia.
</para>
<para>
</simpara>
<simpara>
Si se esperan más subcadenas en el <parameter>format</parameter>
de las disponibles en <parameter>string</parameter>,
&null; será devuelto. En otros casos de error, &false; será devuelto.
</para>
</simpara>
<simpara>
Cuando se usan parámetros opcionales y se alcanza el final de la entrada
leída de <parameter>stream</parameter> antes de que se haya analizado
ningún valor, se devuelve <literal>-1</literal>.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Ejemplo con <function>fscanf</function></title>
<programlisting role="php">
<example>
<title>Ejemplo con <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>Contenido del archivo users.txt</title>
<programlisting role="txt">
</programlisting>
</example>
<example>
<title>Contenido del archivo 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
88 changes: 45 additions & 43 deletions reference/spl/splfileobject/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: d51166ca16fda8e766849505b84f9306ef443f71 Maintainer: seros Status: ready -->
<!-- EN-Revision: 9947012f745f0fb6e083bce5a8c920213ff468b7 Maintainer: seros 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 @@ -14,82 +14,84 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Lee una línea de el fichero e interpreta este de acuerdo a el <parameter>format</parameter>.
</para>
<para>
</simpara>
<simpara>
Cualquier espacio en blanco en el <parameter>format</parameter> string coincide con cualquier espacio en blanco en la línea de
el fichero. Esto significa que incluso un (<literal>\t</literal>) en el formato string puede coincidir con un sólo caracter de
espacio en la secuencia de entrada.
</para>
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<para>
Los valores opcionales asignados.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<simpara>
Los valores opcionales asignados.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Si sólo se pasa un parámetro a este método, los valores analizados serán devueltos
como un array. De lo contrario, si se paran los parámetros opcionales, la función
devolverá el número de valores asignados. Los parámetros opcionales deben ser pasados
por referencia.
</para>
como un <type>array</type>. De lo contrario, si se pasan los parámetros opcionales,
el método devolverá el número de valores asignados. Los parámetros opcionales deben
ser pasados por referencia.
</simpara>
<simpara>
Si se esperan más subcadenas en el <parameter>format</parameter> de las disponibles
en la línea leída del fichero, se devuelve &null;.
</simpara>
<simpara>
Cuando se usan parámetros opcionales y se alcanza el final de la línea leída del
fichero antes de que se haya analizado ningún valor, se devuelve <literal>-1</literal>.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title>Ejemplo de <methodname>SplFileObject::fscanf</methodname></title>
<programlisting role="php">
<example>
<title>Ejemplo de <methodname>SplFileObject::fscanf</methodname></title>
<programlisting role="php">
<![CDATA[
<?php
$file = new SplFileObject("usuarios.txt");
while ($usuarioinfo = $file->fscanf("%s %s %s")) {
list ($nombre, $profesion, $codigopais) = $usuarioinfo;
// Operar con $name $profession $countrycode
list ($nombre, $profesion, $codigopais) = $usuarioinfo;
// Operar con $name $profession $countrycode
}
?>
]]>
</programlisting>
<para>Contenido de usuarios.txt</para>
<programlisting role="txt">
</programlisting>
<simpara>Contenido de usuarios.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