Ruby/IO/read-i

يقرأ التابع read عددًا محدَّدًا من البايتات من المجرى الذي استدعي معه

عندما يُستدعى التابع read في نهاية الملف، فسيعيد إما nil أو ""، بناءً على الطول المُمرَّر إليه، مثلا، ستعيد التعبيرات read و read(nil)‎ و read(0)‎ القيمة ""، فيما سيعيد التعبير read( positive_integer )‎ القيمة nil.

لاحظ أنَّ هذا التابع يتصرف بطريقة مشابهة للدالة fread()‎ في لغة C. وهذا يعني أنَّه سيحاول إجراء استدعاءات النظام read(2)‎ لقراءة البيانات بالطول المحدَّد (أو حتى يصادف محرف نهاية الملف EOF). يستمر هذا السلوك حتى لو لم يكن المجرى في وضع عدم التعطيل (non-blocking mode). (هذا التابع غير حساس لراية عدم التعطيل كغيره من التوابع.) إذا كنت تريد سلوكًا مشابهًا لاستدعاء النظام read(2)‎، فضع في اعتبارك استخدام التوابع readpartial و read_nonblock و sysread.

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

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

المعاملات

length‎

عدد صحيح موجب يمثل عدد البايتات المراد قراءتها دون أي تحويل (الوضع الثنائي) من المجرى. يمكن أن يأخذ القيمة nil. في حالة كان length عددًا صحيحًا، ستُرمّز السلسلة النصية المعادة دائمًا بالترميز ASCII-8BIT.

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

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

outbuf‎

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

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

تعاد السلسلة النصية المقروءة من المجرى المعطى والتي تكون بالحجم length بايت تمامًا، أو تعاد سلسلة نصية أقل من الحجم length إن عُثِرَ على محرف نهاية الملف (EOF)، أو تعاد القيمة nil عند الوصول إلى نهاية الملف (EOF) دون العثور على أي شيء يُقرَأ، أو سلسلة نصية فارغة ("") بناءً على قيمة الطول length

أمثلة

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

f = File.new("testfile")
f.read(16)   #=> "This is line one"
# قراءة الملف بأكمله
open("file") do |f|
  data = f.read   # هذا سيعيد سلسلة نصية حتى لو كان الملف فارغًا
  # ...
end
# التكرار عبر حجم ثابت من البيانات
open("fixed-record-file") do |f|
  while record = f.read(256)
    # ...
  end
end
# التكرار عبر حجم متغير من البيانات
# ستُلحَق كل كتلة من البيانات بالطول 32 بت الخاص بها
open("variable-record-file") do |f|
  while len = f.read(4)
    len = len.unpack("N")[0]  # الطول 32 بت
    record = f.read(len)      # يساوي 0 len هذا سيعيد سلسلة نصية حتى لو كان 
  end
end‎

انظر أيضًا

• التابع pread: يقرأ من المجرى الذي استدعي معه عددًا محدَّدًا من البايتات باستخدام استدعاء النظام pread، ثم يُعيدها كسلسلة نصية من غير تعديل إزاحة (offset) الواصف الأساسي.

• التابع read_nonblock: يقرأ عددًا محدَّدًا من البايتات من المجرى الذي استُدعي معه باستخدام استدعاء النظام read(2)‎ بعد تعيين الراية O_NONBLOCK لواصف الملف (file descriptor) الأساسي.
• التابع readbyte: يقرأ بايتًا واحدًا من المجرى الذي استدعي معه.
• التابع readchar: يقرأ محرفًا واحدًا من المجرى الذي استدعي معه.
• التابع readline: يقرأ سطرًا واحدًا من المجرى الذي استدعي معه.
• التابع readlines: يقرأ كل الأسطر الموجودة في المجرى الذي استدعي معه ثم يعيدها في مصفوفة. 
• التابع readpartial: يقرأ عددًا محدَّدًا من البايتات من المجرى الذي استدعي معه.
• التابع write: يكتب السلاسل النصية المُمرَّرة إليه في المجرى الذي استدعي معه.

مصادر

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