عرض مصدر Ruby/IO/readpartial

<noinclude>{{DISPLAYTITLE: التابع <code>IO.readpartial‎</code> في روبي}}</noinclude>
[[تصنيف: Ruby]]
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby IO]]
يقرأ التابع <code>readpartial</code> عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه.

لن يقوم التابع <code>readpartial</code> بالتعطيل (block) إلا في حال لم يكن في [[Ruby/IO|المجرى]] أي بيانات متوفرة آنذاك. أي أنه لن يُعطِّل في حالة توفر بعض البيانات.

يُطلق التابع <code>readpartial</code> الاستثناء <code>[[Ruby/EOFError|EOFError]]</code> عند نهاية الملف.

صُمِّم التابع <code>readpartial</code> للتعامل مع نوع محدَّد من المجاري (streams) من مِثل الأنابيب (pipes)، والمقابس (sockets)، والطرفية tty، ...إلخ. ولن يقوم بالتعطيل إلا عند عدم توفر أية بيانات حينذاك. هذا يعني أنه سيُعطّل فقط عند تحقق جميع الشروط التالية:
* ذاكرة التخزين المؤقت للبايت (byte buffer) في الكائن <code>[[Ruby/IO|IO]]</code> فارغة.
* محتوى المجرى فارغ.
* المجرى لم يبلغ محرف نهاية الملف (EOF).
عندما يقوم التابع <code>readpartial</code> بالتعطيل، فإنَّه ينتظر البيانات أو محرف نهاية الملف <code>EOF</code> من المجرى. فإذا حصل التابع <code>readpartial</code> على بيانات، فسيعيدها. أما إذا وصل إلى محرف نهاية الملف، فسيُطلق الاستثناء <code>[[Ruby/EOFError|EOFError]]</code>.

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

لاحظ أنَّ التابع <code>readpartial</code> يتصرف بشكل مشابه للتابع <code>[[Ruby/IO/sysread|sysread]]</code>. لكن مع الاختلافات التالية:
* إذا لم يكن المخزن المؤقت للبايت فارغًا، فسيُقرَء من المخزن المؤقت للبايت بدلًا من القراءة من المخزن المؤقت الخاص بالكائن [[Ruby/IO|<code>IO</code>]] كما يفعل <code>[[Ruby/IO/sysread|sysread]]</code>.
* لا يتسبب في الخطأين <code>Errno::EWOULDBLOCK</code> و <code>Errno::EINTR</code>.  عندما يصادف التابع <code>readpartial</code> الخطأين <code>EWOULDBLOCK</code> و <code>EINTR</code> الناتجين عن  استدعاء النظام <code>read</code>، سيحاول إعادة استدعاء النظام.
الأمر الأخير يعني أنَّ التابع <code>readpartial</code> غير حساس لقيمة راية عدم التعطيل ( nonblocking flag). سيقوم بالتعطيل في الحالات التي يقوم فيها التابع <code>[[Ruby/IO/sysread|sysread]]</code> بإطلاق الخطأ <code>Errno::EWOULDBLOCK</code>، كما لو كان <code>fd</code> (واصف الملف) في وضع التعطيل (blocking mode).
==البنية العامة==
<syntaxhighlight lang="ruby">readpartial(maxlen)  → string
readpartial(maxlen, outbuf)→ outbuf‎</syntaxhighlight>
==المعاملات==
===<code>maxlen‎</code>===
عدد صحيح يمثِّل الحد الأقصى للبايتات المراد قراءتها من المجرى المعطى.
===<code>outbuf‎</code>===
في حال إعطاء هذا المعامل الاختياري، فينبغي أن يشير إلى [[Ruby/String|السلسلة النصية]] التي ستتلقى البيانات المقروءة من المجرى. لن يحتوي <code>outbuf</code> إلا على البيانات المستلمة بعد استدعاء التابع حتى لو لم يكن فارغًا في البداية (أي ستُمسَح البيانات القديمة المخزنة فيه مسبقًا).
==القيمة المعادة==
تعاد سلسلة نصية تحوي البيانات المقروءة من المجرى.

==أمثلة==
مثال على استخدام التابع <code>readpartial‎</code>:<syntaxhighlight lang="ruby">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"     ""              ""‎</syntaxhighlight>
==انظر أيضًا==
*التابع [[Ruby/IO/printf|<code>printf</code>]]: ينسق الكائنات المُمرَّرة إليه ثم يكتبها في المجرى الذي استدعي معه. 

*التابع [[Ruby/IO/read-i|<code>read</code>]]: يقرأ عددًا محدَّدًا من البايتات من [[Ruby/IO|المجرى]] الذي استدعي معه.
*التابع <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|مصفوفة]]. 
==مصادر==
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-readpartial قسم التابع readpartial‎ في الصنف IO‎ في توثيق روبي الرسمي.]