Skip to content

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

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
lacatoire wants to merge 1 commit into
base: master
Choose a base branch
from
Open

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

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: nikic Status: ready -->
<!-- EN-Revision: 9947012f745f0fb6e083bce5a8c920213ff468b7 Maintainer: nikic Status: ready -->
<refentry xml:id="function.fscanf" xmlns="http://docbook.org/ns/docbook">
<refnamediv>
<refname>fscanf</refname>
Expand All @@ -16,69 +15,71 @@
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<para>
<simpara>
Die Funktion <function>fscanf</function> ist ähnlich zu
<function>sscanf</function>, wobei sie ihren Input aus
der mit <parameter>stream</parameter> angegebenen Datei liest, und
entsprechend dem angegebenen <parameter>format</parameter>
interpretiert.
</para>
<para>
</simpara>
<simpara>
Beliebige Whitespace-Zeichen (&zb; Leerzeichen, Tabulator etc.)
im Format String gelten mit beliebigen Whitespace-Zeichen des
Input-Streams als übereinstimmend. Das heißt, dass auch ein
Tabulator (<literal>\t</literal>) im Formatstring mit einem einzigen
Leerzeichen im Input-Stream als übereinstimmend gelten kann.
</para>
<para>
</simpara>
<simpara>
Jeder <function>fscanf</function>-Aufruf liest eine Zeile aus der Datei aus.
</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>
Die optional zugewiesenen Werte.
</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>
Die optional zugewiesenen Werte.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<para>
<simpara>
Wenn nur zwei Parameter an die Funktion übergeben wurden, werden die geparseten
Werte in einem Array zurückgegeben. Andernfalls gibt die Funktion die Anzahl
Werte als <type>array</type> zurückgegeben. Andernfalls gibt die Funktion die Anzahl
der zugewiesenen Werte zurück. Die optionalen Parameter müssen per Referenz
übergeben werden.
</para>
<para>
</simpara>
<simpara>
Wenn im <parameter>format</parameter> mehr Teilstrings erwartet werden,
als in <parameter>string</parameter> verfügbar sind, wird &null; zurückgegeben.
Bei anderen Fehlern wird &false; zurückgegeben.
</para>
</simpara>
<simpara>
Wenn optionale Parameter verwendet werden und das Ende des aus
<parameter>stream</parameter> gelesenen Inputs erreicht wird, bevor ein
Wert geparst werden konnte, wird <literal>-1</literal> zurückgegeben.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<para>
<example>
<title><function>fscanf</function>-Beispiel</title>
<programlisting role="php">
<example>
<title><function>fscanf</function>-Beispiel</title>
<programlisting role="php">
<![CDATA[
<?php
$handle = fopen("users.txt", "r");
Expand All @@ -89,36 +90,31 @@ while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
fclose($handle);
?>
]]>
</programlisting>
</example>
</para>
<para>
<example>
<title>Inhalt der Datei users.txt</title>
<programlisting role="txt">
</programlisting>
</example>
<example>
<title>Inhalt der Datei 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
120 changes: 120 additions & 0 deletions reference/spl/splfileobject/fscanf.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,120 @@
<?xml version="1.0" encoding="utf-8"?>
<!-- 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>
<refname>SplFileObject::fscanf</refname>
<refpurpose>Analysiert Input aus einer Datei entsprechend einem Format</refpurpose>
</refnamediv>

<refsect1 role="description">
&reftitle.description;
<methodsynopsis role="SplFileObject">
<modifier>public</modifier> <type class="union"><type>array</type><type>int</type><type>null</type></type><methodname>SplFileObject::fscanf</methodname>
<methodparam><type>string</type><parameter>format</parameter></methodparam>
<methodparam rep="repeat"><type>mixed</type><parameter role="reference">vars</parameter></methodparam>
</methodsynopsis>
<simpara>
Liest eine Zeile aus der Datei und interpretiert sie entsprechend dem
angegebenen <parameter>format</parameter>.
</simpara>
<simpara>
Beliebige Whitespace-Zeichen im <parameter>format</parameter>-String
entsprechen beliebigen Whitespace-Zeichen in der aus der Datei gelesenen
Zeile. Das heißt, dass auch ein Tabulator (<literal>\t</literal>) im
Formatstring einem einzelnen Leerzeichen im Input-Stream entsprechen kann.
</simpara>
</refsect1>

<refsect1 role="parameters">
&reftitle.parameters;
<variablelist>
&strings.scanf.parameter.format;
<varlistentry>
<term><parameter>vars</parameter></term>
<listitem>
<simpara>
Die optional zugewiesenen Werte.
</simpara>
</listitem>
</varlistentry>
</variablelist>
</refsect1>

<refsect1 role="returnvalues">
&reftitle.returnvalues;
<simpara>
Wenn nur ein Parameter an diese Methode übergeben wird, werden die geparsten
Werte als <type>array</type> zurückgegeben. Andernfalls, wenn optionale
Parameter übergeben werden, gibt die Methode die Anzahl der zugewiesenen
Werte zurück. Die optionalen Parameter müssen per Referenz übergeben werden.
</simpara>
<simpara>
Werden mehr Teilstrings in <parameter>format</parameter> erwartet, als in
der aus der Datei gelesenen Zeile verfügbar sind, wird &null; zurückgegeben.
</simpara>
<simpara>
Wenn optionale Parameter verwendet werden und das Ende der aus der Datei
gelesenen Zeile erreicht wird, bevor ein Wert geparst werden konnte, wird
<literal>-1</literal> zurückgegeben.
</simpara>
</refsect1>

<refsect1 role="examples">
&reftitle.examples;
<example>
<title>Beispiel mit <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;
// Tue etwas mit $name $profession $countrycode
}
?>
]]>
</programlisting>
<simpara>Inhalt der Datei users.txt</simpara>
<programlisting role="txt">
<![CDATA[
javier argonaut pe
hiroshi sculptor jp
robert slacker us
luigi florist it
]]>
</programlisting>
</example>
</refsect1>

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

</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->
Loading
Loading