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

<noinclude>{{DISPLAYTITLE: التابع <code>IO.readpartial‎</code> في روبي}}</noinclude>
[[تصنيف: Ruby]]
[[تصنيف: Ruby Method]]
[[تصنيف: Ruby IO]]
يقرأ التابع <code>readpartial</code> من [[Ruby/IO|مجرى د/خ]] <code>maxlen</code> (انظر فقرة البنية العامة) بايتًا على الأكثر .

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

في حال إعطاء الوسيط الاختياري <code>outbuf</code> (انظر فقرة البنية العامة)، فينبغي أن يشير إلى [[Ruby/String|سلسلة نصية]]، والتي ستتلقى البيانات. لن يحتوي الوسيط <code>outbuf</code> إلا البيانات المستلمة بعد استدعاء التابع، حتى لو لم يكن فارغاً في البداية.

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

صُمِّم التابع <code>readpartial</code> لأجل المجاري (streams) من مِثل الأنابيب (pipes)، والمقابس (sockets)، والطرفية tty، إلخ. ولن يقوم بالتعطيل إلا عند عدم توفر أية بيانات فوريا. هذا يعني أنه سيُعطّل فقط عند تحقق جميع الشروط التالية.
* ذاكرة التخزين المؤقت للبايت (byte buffer) في [[Ruby/IO|مجرى د/خ]] فارغة.
* محتوى المجرى فارغ.
* المجرى لم يبلغ محرف نهاية الملف (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>[[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. سيقوم بالتعطيل في الحالات التي يقوم فيها التابع <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>===
سلسلة نصية تتلقى البيانات
==القيمة المُعادة==
يعيد التابع <code>readpartial</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>
==انظر أيضا==
*التابع <code>[[Ruby/IO/readlines-i|readlines]]</code>: يقرأ  كل الأسطر الموجودة في [[Ruby/IO|مجرى د/خ]]، ثم يعيدها في [[Ruby/Array|مصفوفة]].
==مصادر==
*[http://ruby-doc.org/core-2.5.1/IO.html#method-i-readpartial قسم  التابع readpartial‎ في الصنف IO‎ في توثيق روبي الرسمي.]