Ruby/IO/readpartial

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

لن يقوم التابع readpartial بالتعطيل (block) إلا في حال لم يكن في المجرى أي بيانات متوفرة آنذاك. أي أنه لن يُعطِّل في حالة توفر بعض البيانات.

يُطلق التابع readpartial الاستثناء EOFError عند نهاية الملف.

صُمِّم التابع readpartial للتعامل مع نوع محدَّد من المجاري (streams) من مِثل الأنابيب (pipes)، والمقابس (sockets)، والطرفية tty، ...إلخ. ولن يقوم بالتعطيل إلا عند عدم توفر أية بيانات حينذاك. هذا يعني أنه سيُعطّل فقط عند تحقق جميع الشروط التالية:

• ذاكرة التخزين المؤقت للبايت (byte buffer) في الكائن IO فارغة.
• محتوى المجرى فارغ.
• المجرى لم يبلغ محرف نهاية الملف (EOF).

عندما يقوم التابع readpartial بالتعطيل، فإنَّه ينتظر البيانات أو محرف نهاية الملف EOF من المجرى. فإذا حصل التابع readpartial على بيانات، فسيعيدها. أما إذا وصل إلى محرف نهاية الملف، فسيُطلق الاستثناء EOFError.

عندما لا يقوم التابع readpartial بالتعطيل، فسيقوم بالعودة، أو يطلق استثناء مباشرةً. وإذا لم يكن المخزن المؤقت للبايت فارغًا، فسيُعيد البيانات الموجودة فيه. وإلا، إن كان في المجرى بعض المحتويات، فسيعيدها. خلا ذلك، إذا وصل المجرى إلى محرف نهاية الملف، فسيطلق الاستثناء EOFError.

لاحظ أنَّ التابع readpartial يتصرف بشكل مشابه للتابع sysread. لكن مع الاختلافات التالية:

• إذا لم يكن المخزن المؤقت للبايت فارغًا، فسيُقرَء من المخزن المؤقت للبايت بدلًا من القراءة من المخزن المؤقت الخاص بالكائن IO كما يفعل sysread.
• لا يتسبب في الخطأين Errno::EWOULDBLOCK و Errno::EINTR. عندما يصادف التابع readpartial الخطأين EWOULDBLOCK و EINTR الناتجين عن استدعاء النظام read، سيحاول إعادة استدعاء النظام.

الأمر الأخير يعني أنَّ التابع readpartial غير حساس لقيمة راية عدم التعطيل ( nonblocking flag). سيقوم بالتعطيل في الحالات التي يقوم فيها التابع sysread بإطلاق الخطأ Errno::EWOULDBLOCK، كما لو كان fd (واصف الملف) في وضع التعطيل (blocking mode).

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

readpartial(maxlen)  → string
readpartial(maxlen, outbuf)→ outbuf‎

المعاملات

maxlen‎

عدد صحيح يمثِّل الحد الأقصى للبايتات المراد قراءتها من المجرى المعطى.

outbuf‎

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

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

تعاد سلسلة نصية تحوي البيانات المقروءة من المجرى.

أمثلة

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

r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc".
r.readpartial(4096)      #=> "abc"       ""              ""
r.readpartial(4096)      # blocks because buffer and pipe is empty.
r, w = IO.pipe           #               buffer          pipe content
w << "abc"               #               ""              "abc"
w.close                  #               ""              "abc" EOF
r.readpartial(4096)      #=> "abc"       ""              EOF
r.readpartial(4096)      # raises EOFError
r, w = IO.pipe           #               buffer          pipe content
w << "abc\ndef\n"        #               ""              "abc\ndef\n"
r.gets                   #=> "abc\n"     "def\n"         ""
w << "ghi\n"             #               "def\n"         "ghi\n"
r.readpartial(4096)      #=> "def\n"     ""              "ghi\n"
r.readpartial(4096)      #=> "ghi\n"     ""              ""‎

انظر أيضًا

• التابع printf: ينسق الكائنات المُمرَّرة إليه ثم يكتبها في المجرى الذي استدعي معه. 

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

مصادر

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