الفرق بين المراجعتين ل"Ruby/IO/read-i"
جميل-بيلوني (نقاش | مساهمات) ط (تدقيق) |
|||
سطر 3: | سطر 3: | ||
[[تصنيف: Ruby Method]] | [[تصنيف: Ruby Method]] | ||
[[تصنيف: Ruby IO]] | [[تصنيف: Ruby IO]] | ||
− | يقرأ التابع <code>read</code> من [[Ruby/IO| | + | يقرأ التابع <code>read</code> عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه |
− | + | عندما يُستدعى التابع <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>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> إلا على البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغًا في البداية (أي ستُمسَح البيانات القديمة المخزنة فيه مسبقًا). | |
− | ==القيمة | + | ==القيمة المعادة== |
− | + | تعاد [[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" | ||
− | # | + | # قراءة الملف بأكمله |
open("file") do |f| | open("file") do |f| | ||
− | data = f.read # | + | data = f.read # هذا سيعيد سلسلة نصية حتى لو كان الملف فارغًا |
# ... | # ... | ||
end | end | ||
− | # | + | # التكرار عبر حجم ثابت من البيانات |
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 | ||
− | # | + | # التكرار عبر حجم متغير من البيانات |
− | # | + | # ستُلحَق كل كتلة من البيانات بالطول 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] | + | len = len.unpack("N")[0] # الطول 32 بت |
− | record = f.read(len) | + | record = f.read(len) # يساوي 0 len هذا سيعيد سلسلة نصية حتى لو كان |
end | end | ||
end</syntaxhighlight> | end</syntaxhighlight> | ||
− | ==انظر | + | ==انظر أيضًا== |
− | * التابع <code>[[Ruby/IO/read_nonblock|read_nonblock]]</code>: يقرأ | + | * التابع [[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 قسم | + | *[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
: يكتب السلاسل النصية المُمرَّرة إليه في المجرى الذي استدعي معه.