الفرق بين المراجعتين لصفحة: «Ruby/ARGF/read»

المراجعة الحالية بتاريخ 13:12، 3 أكتوبر 2018

يقرأ التابع read عددًا محددًا من البايتات من المجرى ARGF.

البنية العامة

read([length [, outbuf]]) → string, outbuf, or nil

يعالج هذا التابع جميع الملفات الممرَّرة في سطر الأوامر وكأنَّها ملفٌ واحدٌ، لذلك يعيد جميع محتويات هذا الملف الزائف (pseudo file) عند استدعائه دون تمرير أي وسائط.

إذا كانت قيمة الوسيط length عددًا صحيحًا موجبًا، فسيحاول التابع read قراءة عددٍ من البايتات يساوي length دون إجراء أي تحويل (الوضع الثنائي [binary mode]). في حال كان length عددًا صحيحًا (integer)، تكون السلسلة النصية الناتجة مكتوبة بالترميز ASCII-8BIT دائمًا.

لاحظ أنَّ التابع read يسلك نفس سلوك الدالة fread()‎ في لغة C. هذا يعني أنَّ التابع يحاول تنفيذ استدعاءات النظام للدالة read(2)‎ لقراءة البيانات وفق الطول المحدد. إذا كنت تريد أن تسلك هذه الدالة سلوك استدعاءٍ وحيدٍ للدالة read(2)‎، فيمكنك استخدام التابع ‎readpartial أو التابع read_nonblock.

المعاملات

`length`

عددٌ صحيحٌ موجب يحدد عدد البايتات المراد قراءتها. إن أعطيت القيمة nil لهذا الوسيط، فستستمر عملية القراءة من الملف حتى الوصول إلى محرف نهاية الملف (EOF).

`outbuf`

سلسلةٌ نصيةٌ تستعمل لتخزين البيانات المقروءة من المجرى ARGF.

ملاحظة: إن حوى هذا الوسيط أية بيانات سابقة قبل استدعاء الدالة read، فستكتب البيانات الجديدة التي تُقرَأ من المجرى فوق تلك البيانات القديمة.

القيم المعادة

تعاد سلسلة نصية تمثل البيانات التي قُرئت من المجرى ARGF.

تعاد القيمة nil عند الوصول إلى نهاية الملف (EOF) وقبل قراءة أي شيء منه. يعاد عددٌ من البايتات أقل مما هو محدد في الوسيط length عند الوصول إلى نهاية الملف (EOF) أثناء القراءة منه.

إن لم يعطَ الوسيط length أو كانت قيمته تساوي nil، فلن تتوقف عملية القراءة حتى يصل التابع إلى نهاية الملف (EOF) وستجرى عملية تحويل للترميز إذا كان ذلك ممكنًا. يمكن أن تعاد سلسلة نصية حتى لو صودفت نهاية الملف (EOF) قبل قراءة أية بيانات.

إذا كان length يساوي 0، فسيعيد التابع سلسلة نصية فارغة ("").

إن أعطي الوسيط outbuf الاختياري، فستُخزَّن البيانات التي تُقرَأ من المجرى ARGF في هذا الوسيط ثمَّ يعاد.

أمثلة

مثالٌ على استخدام التابع read:

$ echo "small" > small.txt
$ echo "large" > large.txt
$ ./glark.rb small.txt large.txt

ARGF.read      #=> "small\nlarge"
ARGF.read(200) #=> "small\nlarge"
ARGF.read(2)   #=> "sm"
ARGF.read(0)   #=> ""

انظر أيضًا

التابع readbyte: يقرأ البايت التالي من المجرى ARGF ثمَّ يعيده على شكل عدد صحيح (Integer).
التابع read_nonblock: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديَّةً عليا من المجرى ARGF في وضع عدم الحجز (non-blocking mode).
التابع readchar: يقرأ المحرف التالي من المجرى ARGF ثم يعيده على شكل سلسلة نصية.
التابع readline: يقرأ السطر التالي من الملف الحالي في المجرى ARGF.
التابع readlines: يقرأ الملف الحالي في المجرى ARGF بشكل كامل.
التابع readpartial: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديةً عليا من المجرى ARGF.
التابع gets: يقرأ السطر الموالي في الملف الحالي في ARGF.
التابع printf: يطبع الكائن أو الكائنات الممرَّرة إليه على المجرى ios بعد تنسيقها بشكل معين.
التابع to_a: يقرأ الملف الحالي في المجرى ARGF بشكل كامل ثم يضع محتوياته في مصفوفة.
التابع write: يكتب السلسلة النصية الممرَّرة إليها على المجرى ARGF في حال كان الوضع inplace مفعَّلًا.

مصادر

قسم التابع read في الصنف ARGF في توثيق روبي الرسمي.

@@ سطر 5: / سطر 5: @@
 يقرأ التابع <code>read</code> عددًا محددًا من البايتات من المجرى  <code>ARGF</code>.
 ==البنية العامة==
-<syntaxhighlight lang="ruby"> read([length [, outbuf]]) → string, outbuf, or nil </syntaxhighlight>يعالج هذا التابع جميع الملفات الممرَّرة في سطر الأوامر وكأنَّها ملفٌ واحدٌ، لذلك يعيد جميع محتويات هذا الملف الزائف (pseudo file) عند استدعائه دون تمرير أي وسائط.
+<syntaxhighlight lang="ruby">read([length [, outbuf]]) → string, outbuf, or nil </syntaxhighlight>يعالج هذا التابع جميع الملفات الممرَّرة في سطر الأوامر وكأنَّها ملفٌ واحدٌ، لذلك يعيد جميع محتويات هذا الملف الزائف (pseudo file) عند استدعائه دون تمرير أي وسائط.
 إذا كانت قيمة الوسيط <code>length</code> عددًا صحيحًا موجبًا، فسيحاول التابع <code>read</code> قراءة عددٍ من البايتات يساوي <code>length</code> دون إجراء أي تحويل (الوضع الثنائي [binary mode]). في حال كان <code>length</code> عددًا صحيحًا (integer)، تكون السلسلة النصية الناتجة مكتوبة بالترميز <code>ASCII-8BIT</code> دائمًا.
@@ سطر 18: / سطر 18: @@
 === <code>outbuf</code> ===
 سلسلةٌ نصيةٌ تستعمل لتخزين البيانات المقروءة من المجرى  <code>ARGF</code>.
 '''ملاحظة''': إن حوى هذا الوسيط أية بيانات سابقة قبل استدعاء الدالة <code>read</code>، فستكتب البيانات الجديدة التي تُقرَأ من المجرى فوق تلك البيانات القديمة.
 ==القيم المعادة==
-تعاد سلسلة نصية تمثل البيانات التي قُرئت من المجرى  <code>ARGF</code>.
+تعاد سلسلة نصية تمثل البيانات التي قُرئت من المجرى <code>ARGF</code>.
-تعاد القيمة <code>nil</code> عند الوصول إلى نهاية الملف (<code>EOF</code>) وقبل قراءة أي شيء منه. يعاد عددٌ من البايتات أقل مما هو محدد في الوسيط <code>length</code> عند الوصول إلى نهاية الملف (<code>EOF</code>) أثناء القراءة منه.
+تعاد القيمة <code>nil</code> عند الوصول إلى نهاية الملف (EOF) وقبل قراءة أي شيء منه. يعاد عددٌ من البايتات أقل مما هو محدد في الوسيط <code>length</code> عند الوصول إلى نهاية الملف (EOF) أثناء القراءة منه.
-إن لم يعطَ الوسيط <code>length</code> أو كانت قيمته تساوي <code>nil</code>، فلن تتوقف عملية القراءة حتى يصل التابع إلى نهاية الملف (<code>EOF</code>) وستجرى عملية تحويل للترميز إذا كان ذلك ممكنًا. يمكن أن تعاد سلسلة نصية حتى لو صودفت نهاية الملف (<code>EOF</code>) قبل قراءة أية بيانات.
+إن لم يعطَ الوسيط <code>length</code> أو كانت قيمته تساوي <code>nil</code>، فلن تتوقف عملية القراءة حتى يصل التابع إلى نهاية الملف (EOF) وستجرى عملية تحويل للترميز إذا كان ذلك ممكنًا. يمكن أن تعاد سلسلة نصية حتى لو صودفت نهاية الملف (EOF) قبل قراءة أية بيانات.
 إذا كان <code>length</code> يساوي <code>0</code>، فسيعيد التابع سلسلة نصية فارغة (<code>""</code>).
@@ سطر 31: / سطر 32: @@
 ==أمثلة==
 مثالٌ على استخدام التابع <code>read</code>:
-<syntaxhighlight lang="ruby"> $ echo "small" > small.txt
+<syntaxhighlight lang="ruby">$ echo "small" > small.txt
 $ echo "large" > large.txt
 $ ./glark.rb small.txt large.txt
@@ سطر 41: / سطر 42: @@
   </syntaxhighlight>
 ==انظر أيضًا==
-* التابع [[Ruby/ARGF/readbyte | <code>readbyte</code>]]: يقرأ البايت التالي من المجرى  <code>ARGF</code> ثمَّ يعيده على شكل عدد صحيح (<code>Integer</code>).
+* التابع<nowiki/>[[Ruby/ARGF/readbyte | <code>readbyte</code>]]: يقرأ البايت التالي من المجرى <code>ARGF</code> ثمَّ يعيده على شكل عدد صحيح (Integer).
-* التابع [[Ruby/ARGF/read_nonblock | <code>read_nonblock</code>]]: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديَّةً عليا من المجرى  <code>ARGF</code> في وضع عدم الحجز (non-blocking mode).
+* التابع<nowiki/>[[Ruby/ARGF/read_nonblock | <code>read_nonblock</code>]]: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديَّةً عليا من المجرى <code>ARGF</code> في وضع عدم الحجز (non-blocking mode).
-* التابع [[Ruby/ARGF/readchar | <code>readchar</code>]]: يقرأ المحرف التالي من المجرى  <code>ARGF</code> ثم يعيده على شكل سلسلة نصية.
+* التابع<nowiki/>[[Ruby/ARGF/readchar | <code>readchar</code>]]: يقرأ المحرف التالي من المجرى <code>ARGF</code> ثم يعيده على شكل سلسلة نصية.
-* التابع [[Ruby/ARGF/readline | <code>readline</code>]]: يقرأ السطر التالي من الملف الحالي في المجرى  <code>ARGF</code>.
+* التابع<nowiki/>[[Ruby/ARGF/readline | <code>readline</code>]]: يقرأ السطر التالي من الملف الحالي في المجرى <code>ARGF</code>.
-* التابع [[Ruby/ARGF/readlines | <code>readlines</code>]]: يقرأ الملف الحالي في المجرى  <code>ARGF</code> بشكل كامل.
+* التابع<nowiki/>[[Ruby/ARGF/readlines | <code>readlines</code>]]: يقرأ الملف الحالي في المجرى <code>ARGF</code> بشكل كامل.
-* التابع [[Ruby/ARGF/readpartial | <code>readpartial</code>]]: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديةً عليا من المجرى  <code>ARGF</code>.
+* التابع<nowiki/>[[Ruby/ARGF/readpartial | <code>readpartial</code>]]: يقرأ عددًا من البايتات لا يتجاوز قيمةً حديةً عليا من المجرى <code>ARGF</code>.
-* * التابع [[Ruby/ARGF/gets | <code>gets</code>]]: يقرأ التابع [[Ruby/ARGF/gets | <code>gets</code>]] السطر الموالي في الملف الحالي في  <code>ARGF</code>.
+* التابع<nowiki/>[[Ruby/ARGF/gets | <code>gets</code>]]: يقرأ السطر الموالي في الملف الحالي في <code>ARGF</code>.
-* التابع [[Ruby/ARGF/printf | <code>printf</code>]]: يطبع الكائن أو الكائنات الممرَّرة إليه على المجرى <code>ios</code> بعد تنسيقها بشكل معين.
+* التابع<nowiki/>[[Ruby/ARGF/printf | <code>printf</code>]]: يطبع الكائن أو الكائنات الممرَّرة إليه على المجرى <code>ios</code> بعد تنسيقها بشكل معين.
-* التابع [[Ruby/ARGF/to_a | <code>to_a</code>]]: يقرأ الملف الحالي في المجرى  <code>ARGF</code> بشكل كامل ثم يضع محتوياته في مصفوفة.
+* التابع<nowiki/>[[Ruby/ARGF/to_a | <code>to_a</code>]]: يقرأ الملف الحالي في المجرى <code>ARGF</code> بشكل كامل ثم يضع محتوياته في مصفوفة.
-* التابع [[Ruby/ARGF/write | <code>write</code>]]: يكتب السلسلة النصية الممرَّرة إليها على المجرى  <code>ARGF</code> في حال كان الوضع <code>inplace</code> مفعَّلًا.
+* التابع<nowiki/>[[Ruby/ARGF/write | <code>write</code>]]: يكتب السلسلة النصية الممرَّرة إليها على المجرى <code>ARGF</code> في حال كان الوضع <code>inplace</code> مفعَّلًا.
 ==مصادر==
 * [http://ruby-doc.org/core-2.5.1/ARGF.html#method-i-read قسم التابع read في الصنف ARGF في توثيق روبي الرسمي.]