الفرق بين المراجعتين ل"Ruby/IO/read-i"

من موسوعة حسوب
< Ruby‏ | IO
اذهب إلى التنقل اذهب إلى البحث
ط (تدقيق)
 
سطر 3: سطر 3:
 
[[تصنيف: Ruby Method]]
 
[[تصنيف: Ruby Method]]
 
[[تصنيف: Ruby IO]]
 
[[تصنيف: Ruby IO]]
يقرأ التابع <code>read</code> من [[Ruby/IO|مجرى د/خ]] <code>length</code> بايتًا (انظر فقرة البنية العامة). يجب أن يكون الوسيط <code>length</code> عددًا صحيحًا غير سلبي أو يكون <code>nil</code>.
+
يقرأ التابع <code>read</code> عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه
  
إن كان <code>length</code> عددًا صحيحًا موجبًا، سيحاول التابع <code>read</code> قراءة <code>length</code> بايت دون أي تحويل (الوضع الثنائي).  
+
عندما يُستدعى التابع <code>read</code> في نهاية الملف، فسيعيد إما <code>nil</code> أو <code>""</code>، بناءً على الطول المُمرَّر إليه، مثلا، ستعيد التعبيرات <code>read</code> و <code>read(nil)‎</code> و <code>read(0)‎</code> القيمة <code>""</code>، فيما سيعيد التعبير <code>read( positive_integer )‎</code> القيمة <code>nil</code>.
  
سيُعيد التابع <code>read</code> القيمة <code>nil</code> إذا تمت مصادفة محرف نهاية الملف (<code>EOF</code>) قبل إيجاد أي شيء يمكن قراءته. كما سيعيد عددا من البايتات أقل من العدد<code>length</code> إذا تمت مصادفة محرف نهاية الملف (<code>EOF</code>) أثناء القراءة. في حالة كان <code>length</code> عددا صحيحا، ستُرمّز [[Ruby/String|السلسلة النصية]] الناتجة دائمًا ب[[Ruby/Encoding|الترميز]] <code>ASCII-8BIT</code>.
+
لاحظ أنَّ هذا التابع يتصرف بطريقة مشابهة للدالة <code>fread()‎</code> في لغة [[C]]. وهذا يعني أنَّه سيحاول إجراء استدعاءات النظام <code>read(2)‎</code> لقراءة البيانات بالطول المحدَّد (أو حتى يصادف محرف نهاية الملف <code>EOF</code>). يستمر هذا السلوك حتى لو لم يكن [[Ruby/IO|المجرى]] في وضع عدم التعطيل (non-blocking mode). (هذا التابع غير حساس لراية عدم التعطيل كغيره من التوابع.) إذا كنت تريد سلوكًا مشابهًا لاستدعاء النظام <code>read(2)‎</code>، فضع في اعتبارك  استخدام التوابع <code>[[Ruby/IO/readpartial|readpartial]]</code> و <code>[[Ruby/IO/read_nonblock|read_nonblock]]</code> و <code>[[Ruby/IO/sysread|sysread]]</code>.
 
 
إذا تم حذف الوسيط <code>length</code>، أو كان يساوي <code>nil</code>، فسيقرأ التابع <code>read</code> حتى يصادف محرف نهاية الملف <code>EOF</code>، وسيتم تطبيق تحويل الترميز إن كان ذلك ممكنًا. ستُعاد [[Ruby/String|سلسلة نصية]] حتى لو صودِف محرف نهاية الملف EOF قبل قراءة أي بيانات.
 
 
 
إن كان <code>length</code> يساوي الصفر، فستُعاد [[Ruby/String|سلسلة نصية]] فارغة (<code>""</code>).
 
 
 
في حال إعطاء الوسيط الاختياري <code>outbuf</code> (انظر فقرة البنية العامة)، فينبغي أن يشير إلى [[Ruby/String|سلسلة نصية]]، والتي ستتلقى البيانات. لن يحتوي <code>outbuf</code> إلا البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغاً في البداية.
 
 
 
عندما يُستدعى التابع <code>read</code> في نهاية الملف، فسيعيد إما <code>nil</code> أو <code>""</code>، بناءً على الطول <code>length</code>، مثلا، ستعيد التعبيرات <code>read</code> و <code>read(nil)‎</code> و <code>read(0)‎</code> القيمة <code>""</code>، فيما سيعيد التعبير <code>read( positive_integer )‎</code> القيمة <code>nil</code>.
 
 
 
لاحظ أن هذا التابع يتصرف بطريقة مشابهة للدالة <code>fread()‎</code> في لغة C. وهذا يعني أنه سيحاول إجراء استدعاءات النظام <code>read(2)‎</code> لقراءة البيانات بالطول المحدد (أو حتى يصادف محرف نهاية الملف <code>EOF</code>). يستمر هذا السلوك حتى لو لم يكن [[Ruby/IO|مجرى د/خ]] في وضع عدم التعطيل (non-blocking mode). (هذا التابع غير حساس لراية عدم التعطيل كغيره من التوابع.) إذا كنت تريد سلوكا مشابها لاستدعاء النظام <code>read(2)‎</code>، فضع في اعتبارك  استخدام التوابع <code>[[Ruby/IO/readpartial|readpartial]]</code> و <code>[[Ruby/IO/read_nonblock|read_nonblock]]</code> و <code>[[Ruby/IO/sysread|sysread]]</code>.
 
 
==البنية العامة==
 
==البنية العامة==
 
<syntaxhighlight lang="ruby">read([length [, outbuf]]) → string, outbuf, or nil‎</syntaxhighlight>
 
<syntaxhighlight lang="ruby">read([length [, outbuf]]) → string, outbuf, or nil‎</syntaxhighlight>
 
==المعاملات==
 
==المعاملات==
 
===<code>length‎</code>===
 
===<code>length‎</code>===
عدد صحيح يمثل الطول
+
[[Ruby/Integer|عدد صحيح]] موجب يمثل عدد البايتات المراد قراءتها دون أي تحويل (الوضع الثنائي) من المجرى. يمكن أن يأخذ القيمة <code>nil</code>. في حالة كان <code>length</code> عددًا صحيحًا، ستُرمّز [[Ruby/String|السلسلة النصية]] المعادة دائمًا ب[[Ruby/Encoding|الترميز]] <code>ASCII-8BIT</code>.
 +
 
 +
إذا تم حذف المعامل <code>length</code> أو كان يساوي <code>nil</code>، فسيقرأ التابع <code>read</code> جميع محتويات المجرى حتى يصادف محرف نهاية الملف <code>EOF</code>، وسيتم تطبيق تحويل الترميز إن كان ذلك ممكنًا. ستُعاد [[Ruby/String|سلسلة نصية]] فارغة لو صودِف محرف نهاية الملف قبل قراءة أي بيانات.
 +
 
 +
إن كان <code>length</code> يساوي الصفر، فستُعاد [[Ruby/String|سلسلة نصية]] فارغة (<code>""</code>).
 
===<code>outbuf‎</code>===
 
===<code>outbuf‎</code>===
سلسلة نصية تتلقى البيانات
+
في حال إعطاء هذا المعامل الاختياري، فينبغي أن يشير إلى [[Ruby/String|السلسلة النصية]] التي ستتلقى البيانات المقروءة من المجرى. لن يحتوي <code>outbuf</code> إلا على البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغًا في البداية (أي ستُمسَح البيانات القديمة المخزنة فيه مسبقًا).
==القيمة المُعادة==
+
==القيمة المعادة==
يُعيد التابع <code>read</code> [[Ruby/String|السلسلة النصية]] المقروءة أو القيمة <code>nil</code> أو [[Ruby/String|سلسلة نصية]] فارغة (<code>""</code>)  بناءً على قيمة الطول <code>length</code>
+
تعاد [[Ruby/String|السلسلة النصية]] المقروءة من المجرى المعطى والتي تكون بالحجم <code>length</code> بايت تمامًا، أو تعاد سلسلة نصية أقل من الحجم <code>length</code> إن عُثِرَ على محرف نهاية الملف (EOF)، أو تعاد القيمة <code>nil</code> عند الوصول إلى نهاية الملف (EOF) دون العثور على أي شيء يُقرَأ، أو [[Ruby/String|سلسلة نصية]] فارغة (<code>""</code>)  بناءً على قيمة الطول <code>length</code>
  
 
==أمثلة==
 
==أمثلة==
سطر 32: سطر 26:
 
<syntaxhighlight lang="ruby">f = File.new("testfile")
 
<syntaxhighlight lang="ruby">f = File.new("testfile")
 
f.read(16)  #=> "This is line one"
 
f.read(16)  #=> "This is line one"
# read whole file
+
# قراءة الملف بأكمله
 
open("file") do |f|
 
open("file") do |f|
   data = f.read  # This returns a string even if the file is empty.
+
   data = f.read  # هذا سيعيد سلسلة نصية حتى لو كان الملف فارغًا
 
   # ...
 
   # ...
 
end
 
end
# iterate over fixed length records
+
# التكرار عبر حجم ثابت من البيانات
 
open("fixed-record-file") do |f|
 
open("fixed-record-file") do |f|
 
   while record = f.read(256)
 
   while record = f.read(256)
سطر 43: سطر 37:
 
   end
 
   end
 
end
 
end
# iterate over variable length records,
+
# التكرار عبر حجم متغير من البيانات
# each record is prefixed by its 32-bit length
+
# ستُلحَق كل كتلة من البيانات بالطول 32 بت الخاص بها
 
open("variable-record-file") do |f|
 
open("variable-record-file") do |f|
 
   while len = f.read(4)
 
   while len = f.read(4)
     len = len.unpack("N")[0]   # 32-bit length
+
     len = len.unpack("N")[0] # الطول 32 بت
     record = f.read(len)       # This returns a string even if len is 0.
+
     record = f.read(len)     # يساوي 0 len هذا سيعيد سلسلة نصية حتى لو كان
 
   end
 
   end
 
end‎</syntaxhighlight>
 
end‎</syntaxhighlight>
==انظر أيضا==
+
==انظر أيضًا==
* التابع <code>[[Ruby/IO/read_nonblock|read_nonblock]]</code>: يقرأ على الأكثر <code>maxlen</code> بايتًا من [[Ruby/IO|مجرى د/خ]]  
+
* التابع [[Ruby/IO/pread|<code>pread</code>]]: يقرأ من المجرى الذي استدعي معه عددًا محدَّدًا من البايتات باستخدام استدعاء النظام <code>pread</code>، ثم يُعيدها ك[[Ruby/String|سلسلة نصية]] من غير تعديل إزاحة (offset) الواصف الأساسي.
 +
 
 +
* التابع <code>[[Ruby/IO/read_nonblock|read_nonblock]]</code>: يقرأ عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استُدعي معه باستخدام استدعاء النظام <code>read(2)‎</code> بعد تعيين الراية <code>O_NONBLOCK</code> لواصف الملف (file descriptor) الأساسي.
 +
* التابع [[Ruby/IO/readbyte|<code>readbyte</code>]]: يقرأ بايتًا واحدًا من المجرى الذي استدعي معه.
 +
* التابع [[Ruby/IO/readchar|<code>readchar</code>]]: يقرأ محرفًا واحدًا من [[Ruby/IO|المجرى]] الذي استدعي معه.
 +
* التابع [[Ruby/IO/readline|<code>readline</code>]]: يقرأ سطرًا واحدًا من المجرى الذي استدعي معه.
 +
* التابع [[Ruby/IO/readlines-i|<code>readlines</code>]]: يقرأ كل الأسطر الموجودة في [[Ruby/IO|المجرى]] الذي استدعي معه ثم يعيدها في [[Ruby/Array|مصفوفة]]. 
 +
* التابع [[Ruby/IO/readpartial|<code>readpartial</code>]]: يقرأ عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه.
 +
* التابع [[Ruby/IO/write-i|<code>write</code>]]: يكتب [[Ruby/String|السلاسل النصية]] المُمرَّرة إليه في [[Ruby/IO|المجرى]] الذي استدعي معه.
 
==مصادر==
 
==مصادر==
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-read قسم التابع read‎ في الصنف IO‎ في توثيق روبي الرسمي.]
+
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-read قسم التابع read‎ في الصنف IO‎ في توثيق روبي الرسمي.]

المراجعة الحالية بتاريخ 08:35، 23 ديسمبر 2018

يقرأ التابع 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: يكتب السلاسل النصية المُمرَّرة إليه في المجرى الذي استدعي معه.

مصادر