عرض مصدر PHP/fscanf

<noinclude>{{DISPLAYTITLE:الدالة <code>fscanf()</code>‎ في PHP}}</noinclude>
(PHP 4 >= 4.0.1, PHP 5, PHP 7)

تحلِّل الدالة <code>fscanf()‎</code> المدخلات من الملف وفقًا لتنسيق محدَّد.

== الوصف ==
<syntaxhighlight lang="php">
mixed fscanf ( resource $handle , string $format [, mixed &$... ] )
</syntaxhighlight>تشبه هذه الدالة الدالة <code>[[PHP/sscanf|sscanf()‎]]</code> باستثناء أنَّها تأخذ مدخلاتها من الملف الذي يشير إليه المورد <code>handle</code> ثمَّ تُفسِّر هذه المدخلات وفقًا للتنسيق <code>format</code> المُعطى الذي شُرح بالتفصيل في صفحة الدالة <code>[[PHP/sprintf|sprintf()‎]]</code>.

'''ملاحظة''': أيُّ فراغ أبيض (whitespace) موجود في السلسلة النصيَّة <code>format</code> سيتطابق مع أي محرف فراغ أبيض يُعثر عليه في الملف. هذا يعني أنَّه يمكن أن يتطابق حتى محرف مسافة الجدولة <code>‎\t</code> مع محرف فراغ عادي.

ستقرأ الدالة <code>fscanf()‎</code> سطرًا واحدًا من الملف في كلِّ مرة تُستدعى فيها.

== المعاملات ==

=== <code>handle</code> ===
مؤشِّر (pointer) يشير إلى ملف. يجب أن يكون سليمًا، ويشير إلى ملف فُتح بطريقة صحيحة باستعمال الدالة <code>[[PHP/fopen|fopen()‎]]</code> أو الدالة <code>[[PHP/fsockopen|fsockopen()‎]]</code> ولم يُغلق بعد باستعمال الدالة <code>[[PHP/fclose|fclose()‎]]</code>.

=== <code>format</code> ===
التنسيق المحدَّد الذي ستُحلل البيانات بناءً عليه. راجع الدالة <code>[[PHP/sprintf|sprintf()‎]]</code> للاطلاع على الشرح المفصَّل لهذا المعامل.

=== <code>...</code> ===
المعاملات الاختياريَّة المُمررة بالمرجعيَّة.

== القيم المعادة ==
إن مُرِّر إلى هذه الدالة معاملين فقط، فستعيد القيم التي حلَّلتها في مصفوفة. أمَّا إن مُرِّر إلى الدالة معاملات اختياريَّة، فستسند هذه الدالة القيم التي حلَّلتها من الملف إلى تلك المعاملات وستعيد عدد هذه القيم؛ أي هو نفسه عدد القيم التي حلَّلتها وأسندتها إلى المعاملات. يجب تمرير المعاملات الاختياريَّة بالمرجعيَّة.

== أمثلة ==
المثال 1: استعمال الدالة <code>fscanf()‎</code><syntaxhighlight lang="php">
<?php
$handle = fopen("users.txt", "r");
while ($userinfo = fscanf($handle, "%s\t%s\t%s\n")) {
    list ($name, $profession, $countrycode) = $userinfo;
    //... افعل هنا شيئًا للقيم
}
fclose($handle);
?>
</syntaxhighlight>المثال 2: محتوى الملف users.txt<syntaxhighlight lang="text">
javier  argonaut        pe
hiroshi sculptor        jp
robert  slacker us
luigi   florist it
</syntaxhighlight>

== انظر أيضًا ==
* الدالة <code>[[PHP/fgets|fgets()‎]]</code>: تجلب سطرًا واحدًا من ملف.
* الدالة <code>[[PHP/fgets|fgetss()‎]]</code>: تجلب سطرًا من ملف وتزيل وسوم HTML.
* الدالة <code>[[PHP/fread|fread()‎]]</code>: تقرأ من الملف بطريقة آمنة ثنائيًّا.
* الدالة <code>[[PHP/sscanf|sscanf()‎]]</code>: تحلِّل المدخلات من سلسلة نصيَّة وفقًا لتنسيق محدَّد.
* الدالة <code>[[PHP/printf|printf()‎]]</code>: طباعة سلسلة نصيَّة بتنسيق محدَّد.
* الدالة <code>[[PHP/sprintf|sprintf()‎]]</code>: تعيد سلسلة نصيَّة منسَّقة.

== مصادر ==
* [http://php.net/manual/en/function.fscanf.php صفحة الدالة fscanf في توثيق PHP الرسمي.]
[[تصنيف:PHP]]
[[تصنيف:PHP Function]]
[[تصنيف:PHP Filesystem]]