Ruby/IO/read-i

يقرأ التابع read من مجرى د/خ length بايتًا (انظر فقرة البنية العامة). يجب أن يكون الوسيط length عددًا صحيحًا غير سلبي أو يكون nil.

إن كان length عددًا صحيحًا موجبًا، سيحاول التابع read قراءة length بايت دون أي تحويل (الوضع الثنائي).

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

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

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

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

عندما يُستدعى التابع read في نهاية الملف، فسيعيد إما nil أو ""، بناءً على الطول length، مثلا، ستعيد التعبيرات 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‎

عدد صحيح يمثل الطول

outbuf‎

سلسلة نصية تتلقى البيانات

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

يُعيد التابع read السلسلة النصية المقروءة أو القيمة nil أو سلسلة نصية فارغة ("") بناءً على قيمة الطول length

أمثلة

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

f = File.new("testfile")
f.read(16)   #=> "This is line one"
# read whole file
open("file") do |f|
  data = f.read   # This returns a string even if the file is empty.
  # ...
end
# iterate over fixed length records
open("fixed-record-file") do |f|
  while record = f.read(256)
    # ...
  end
end
# iterate over variable length records,
# each record is prefixed by its 32-bit length
open("variable-record-file") do |f|
  while len = f.read(4)
    len = len.unpack("N")[0]   # 32-bit length
    record = f.read(len)       # This returns a string even if len is 0.
  end
end‎

انظر أيضا

• التابع read_nonblock: يقرأ على الأكثر maxlen بايتًا من مجرى د/خ

مصادر

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